---
title: Servers
description: Make a machine a Carbon server with carbon server, give it a public address, and manage the app's list of servers with carbon machine.
sidebar:
  order: 8
---

Two command groups, for two sides of the same setup:

- `carbon server` runs on the machine that will **be** a server: a Linux box, or a Mac with no Carbon app. It installs what is missing and keeps the server running.
- `carbon machine` runs on your Mac and edits the **app's list** of servers, the same list as Settings → Servers.

For the full walkthrough of putting Carbon on a Linux server, see [Connect a server](/docs/server).

## carbon server

```bash
carbon server install
carbon server status
```

| Command | What it does |
|---|---|
| `install` | Installs what this machine is missing, then starts the server in the background. |
| `start` | Runs the server in the background, surviving logout and reboot. |
| `run [args]` | Runs the server in this terminal instead. |
| `stop` | Stops the server and removes it from the background. |
| `status` | Says whether the server is running, and its public address if it has one. |
| `tunnel on` / `tunnel off` | Puts a public address in front of the server, or takes it down. |

### Install

```bash
carbon server install
carbon server install --tools git,gh,claude_code
```

Lists what is already here, asks what to install from what is missing, then starts the server. The choices are git, the GitHub CLI and the five agents (`claude_code`, `codex`, `pi`, `fx`, `grok`). On Linux it also offers **Browser for agents**, the system libraries `carbon browser` needs, and **ffmpeg**, which `carbon browser record` needs. Those two install with apt only.

`--tools` installs the ones you name without asking. With no terminal to ask in and no `--tools`, it installs nothing and says what is missing. Anything that needs admin rights it cannot get is printed for you to run yourself.

It then lists the agent logins still to do, and ends by printing the SSH line to paste into the app's **Add server**.

A first install from `install.sh` runs this for you on any machine without the Carbon app.

### Start, run, stop

```bash
carbon server start
carbon server run --port 7317
carbon server stop
```

On Linux, `start` installs a systemd user service, `carbon.service`. If your user has no linger, the server stops when you log out, and `start` prints `sudo loginctl enable-linger <user>` to fix that. Read its log with `journalctl --user -u carbon`. With no systemd user session at all, `start` refuses; run `carbon server run` under tmux or nohup instead.

On a Mac with no Carbon app, `start` installs a login agent. Its log is `~/.carbon/server.log`. It runs only while your user is logged in, so a headless Mac wants automatic login. For the app on another Mac to reach it, turn on Remote Login in System Settings → General → Sharing.

`run` passes what follows to the server. Its one option is `--port`: the port it listens on, 7317 by default, or `0` to pick a free one.

`start` never restarts a server that is already running, since that stops its agents. After `carbon update`, it prints the command that restarts it onto the new version.

`stop` stops the background server and removes the service. It removes only the server `carbon server start` installed.

### Public address

```bash
carbon server tunnel on
```

Gives the server a public address that stays the same across restarts, and waits for it, up to two minutes. In a terminal it prints the address and a line to paste into the app: Settings → Servers → Add server → Use an address and token. Anyone holding that line can use the server.

`carbon server tunnel off` takes the address down. The server is then reachable over SSH alone. The address is off until you turn it on.

### On a Mac with the Carbon app

The app runs this Mac's server, so `start`, `run` and `status` are refused with `the Carbon app runs this Mac's server`. `install` still installs tools and then stops. `tunnel on` and `tunnel off` work, and do the same as the Remote access switch in Settings → Servers.

To run a second server beside the app anyway, give it its own data directory with `CARBON_HOME`.

### Older spellings

These still work, because the app runs them on servers with older CLIs:

| Older | Now |
|---|---|
| `carbon setup` (`--install <tools>`) | `carbon server install` (`--tools`) |
| `carbon serve` | `carbon server run` |
| `carbon service start` / `status` / `uninstall` / `tunnel on\|off` | `carbon server start` / `status` / `stop` / `tunnel on\|off` |

## carbon machine

```bash
carbon machine add vps root@203.0.113.7
carbon machine ls
```

Edits the app's list of servers. Changes show in Settings → Servers as you run them. These run on a Mac with the app; on a server with no app they are refused, since the list lives in the Mac app.

| Command | What it does |
|---|---|
| `add <name> <address>` | Adds a server. It connects first, and is saved only if that works. |
| `ls` | Lists the servers: name, address, and `connected`, `connecting`, `disconnected` or `off`, with the last error if it failed. `--json` for scripts. |
| `rename <name> <new-name>` | Renames a server. An empty name, `""`, puts back its host. |
| `connect <name>` | Connects now, or tries again on one that failed. Waits and says how it went. |
| `disconnect <name>` | Stops connecting. It stays on the list with its token, and its agents keep running. |
| `rm <name>` | Takes a server off the list, with its token. Its agents keep running there. |

Each name belongs to one server; `add` and `rename` refuse a name another server has.

### Add a server

The address is the line you log in with, or a `ws://` address:

```bash
carbon machine add vps root@203.0.113.7
carbon machine add vps ssh -p 2222 root@203.0.113.7
carbon machine add vps my-ssh-alias
cat serve-token | carbon machine add vps ws://127.0.0.1:7317
carbon machine add --token-file serve-token vps ws://127.0.0.1:7317
```

For SSH, everything after the name is the login, so it needs no quotes. The app logs in with your Mac's own `ssh` and reads the server's token over that login. A login can take most of a minute.

A `ws://` address needs the server's token, from `~/.carbon/serve-token` on the server. Pass it with `--token-file`, which must come before the name, or on standard input. There is no flag that takes the token itself, so it never lands in your shell history.

If the connection fails, `add` saves nothing and says why: an unknown host key, a login that wants a password, no Carbon on the server.

## Limits

- `carbon server` installs browser libraries and ffmpeg with apt alone.
- On a Mac, the background server runs only while you are logged in.
- `carbon machine` works only where the Carbon app runs.