---
title: tld serve
description: Run a local tlDiagram instance on your machine. Full editor, no cloud required.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

`tld serve` launches a complete tlDiagram web app right on your machine. Same editor that powers tldiagram.com, running locally with an embedded SQLite database.


```bash
tld serve
```

## What you get

A full tlDiagram editor at `http://127.0.0.1:8060`. You can:
- Create and edit architecture diagrams visually
- Use all keyboard shortcuts (WASD navigation, C to add nodes, etc.)
- Export and import YAML workspace files
- View diagrams generated by `tld watch` and `tld analyze`

Everything stays on your machine. No data leaves unless you explicitly push to the cloud with `tld apply`.

## Modes

### Background (default)

```bash
tld serve
```

Starts the server as a background process. Prints connection details and exits the terminal. The server keeps running.

```
────────────────────────────────────
  Mode             background
  PID              12345
  Server status    using existing local data
  Bind address     127.0.0.1:8060
  DB               ~/.local/share/tldiagram/tld.db
  Config path      ~/.config/tldiagram/tld.yaml
────────────────────────────────────
  tlDiagram available at:  http://127.0.0.1:8060
────────────────────────────────────
  Run 'tld stop' to shut down the server
```

If a server is already running, it tells you instead of starting a second one.

## Host and port

```bash
# Custom port
tld serve --port 9090

# Bind to all interfaces (accessible from other machines)
tld serve --host 0.0.0.0 --port 8080
```

Defaults: `127.0.0.1:8060`. Set permanently in your global config:

```bash
tld config set serve.port 9090
```

Or via environment variables: `PORT=9090` or `TLD_ADDR=:9090`.

## Data directory

The local server stores its SQLite database and logs in a data directory:

```
~/.local/share/tldiagram/
  tld.db       # SQLite database
  server.log   # Server logs
  tld.pid      # Process ID file
```

Override with `--data-dir` or `TLD_DATA_DIR`:

```bash
tld serve --data-dir /custom/path
```
:::tip
Configure these in your global config to avoid passing flags every time:
:::

## What's stored locally

The local server is fully self-contained:

- **Diagrams**: Stored in SQLite. Populated by `tld watch` or `tld analyze`
- **Logs**: Written to `server.log` in the data directory
- **Config**: Read from your global tld config file

## When the server won't start

If the port is already in use, change it:

```bash
tld serve --port 8061
```

If the data directory isn't writable, check permissions or use a different path:

```bash
tld serve --data-dir /tmp/tld-test
```

Check the logs:

```bash
cat ~/.local/share/tldiagram/server.log
```