> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# Octop Server Commands: init, run, service, and update

These commands control the Octop server lifecycle — bootstrapping a fresh install, starting the server process, registering it as a system service, and keeping it up to date. Run them in order the first time you set up Octop, and return to them whenever you need to manage or upgrade your deployment.

## `octop init`

Bootstrap `~/.octop/` with the SQLite database, JWT secret, and first admin account. Run this once before starting the server for the first time.


```bash Interactive setup
octop init
```
```bash Non-interactive setup
octop init --admin-username admin --admin-password mypassword1 --yes
```


### Options

| Option                      | Env var                    | Description                                             |
| --------------------------- | -------------------------- | ------------------------------------------------------- |
| `--admin-username TEXT`     | `OCTOP_ADMIN_USERNAME`     | Username for the first admin account                    |
| `--admin-password TEXT`     | `OCTOP_ADMIN_PASSWORD`     | Password for the first admin account                    |
| `--admin-display-name TEXT` | `OCTOP_ADMIN_DISPLAY_NAME` | Display name for the first admin account                |
| `--force`                   | —                          | Wipe existing `~/.octop/` contents before bootstrapping |
| `--yes`                     | —                          | Skip all interactive prompts                            |


> **NOTE**
> 
> `octop init` is idempotent on the database — running it again on an existing install is safe and only applies missing migrations. Use `--force` to wipe `~/.octop/` and start completely fresh.
> 


***

## `octop run`

Start the Octop server in the foreground using uvicorn. This serves the web UI, HTTP/SSE API, and IM channel listeners on a single process.


```bash Default
octop run
```
```bash Custom host and port
octop run --host 0.0.0.0 --port 8088
```
```bash HTTPS with self-signed certificate
octop run --ssl
```
```bash HTTPS with your own certificate
octop run --ssl --certfile /path/cert.pem --keyfile /path/key.pem
```


### Options

| Option                   | Default     | Description                                                                    |
| ------------------------ | ----------- | ------------------------------------------------------------------------------ |
| `--host TEXT`            | `127.0.0.1` | Bind host. Precedence: this flag > `OCTOP_BIND_HOST` > `config.json` > default |
| `--port INTEGER`         | `8088`      | Listen port. Precedence: this flag > `OCTOP_PORT` > `config.json` > default    |
| `--reload / --no-reload` | off         | Enable uvicorn auto-reload (development only)                                  |
| `--ssl / --no-ssl`       | off         | Enable HTTPS                                                                   |
| `--certfile PATH`        | —           | TLS certificate in PEM format                                                  |
| `--keyfile PATH`         | —           | TLS private key in PEM format                                                  |
| `--log-level`            | `info`      | One of: `debug`, `info`, `warning`, `error`                                    |


> **WARNING**
> 
> Do not use `--reload` in production. Auto-reload restarts the process on every file change and is intended for local development only.
> 



> **NOTE**
> 
> Passing `--host` or `--port` writes that value into `config.json` before uvicorn starts. A corrupt `config.json` is a hard error — Octop will not merge into an empty object and wipe the rest of the file.
> 


***

## `octop service`

Register Octop as a system service so it starts automatically on boot and runs in the background.


```bash Start (and install if missing)
octop service start
```
```bash Stop
octop service stop
```
```bash Restart
octop service restart
```
```bash Check status and health
octop service status
```



> **NOTE**
> 
> `octop service` auto-detects the platform: it uses **systemd** on Linux and **launchd** on macOS. The `status` subcommand probes the HTTP health endpoint and prints journal or log hints on failure. Force the scope with `--scope user` or `--scope system` (or via `OCTOP_SERVICE_SCOPE`). On Linux, `start` and `restart` install a systemd drop-in (`octop.service.d/10-nofile.conf`) with `LimitNOFILE=65535`. The main unit file is not rewritten unless it is missing or you pass `--force-install`. To undo: delete the drop-in, then `systemctl daemon-reload && systemctl restart octop`.
> 


***

## `octop update`

Check for a newer Octop release on PyPI and install it automatically. Checks default to **stable releases only**. The web UI **Admin → Application Settings → App Updates** uses the same rule unless you turn on pre-releases. For every install method (web UI, install script, Docker, FnOS), see [Upgrade](/en/guide/guides/upgrade.md).


```bash Check and install
octop update
```
```bash Check only, do not install
octop update --check
```
```bash Include pre-releases
octop update --allow-prerelease
```


### Options

| Option                 | Description                                                           |
| ---------------------- | --------------------------------------------------------------------- |
| `--check / --no-check` | Report the available version without installing                       |
| `--yes` / `-y`         | Skip the confirmation prompt                                          |
| `--verbose` / `-v`     | Print installer output                                                |
| `--allow-prerelease`   | Include alpha / beta / rc / dev versions when checking and installing |

***

## `octop captcha`

Clear stored login-captcha settings against the local database. Use this when a misconfigured cloud provider (wrong keys, unreachable vendor, hostname not allowlisted) locks everyone out of the web UI — the settings page itself requires login.

```bash
octop captcha reset
```

Login then falls back to the built-in slider. This command does **not** change `OCTOP_CAPTCHA_*` in the environment file; unset those yourself if they caused the lockout. Restart `octop run` if it is already running.

***

## `octop migrate`

Copy an OpenClaw or Hermes Agent setup into one expert. The command starts a short-lived in-process server. If `octop run` is already running, restart it afterwards so the new providers and channels load. The full walkthrough is in [Migrate from OpenClaw](/en/guide/migrate/openclaw.md) and [Migrate from Hermes Agent](/en/guide/migrate/hermes.md).

```bash
octop --agent <id> migrate openclaw --dry-run
octop --agent <id> migrate hermes --from /srv/hermes --skip channels
```

| Source   | What moves                                                    |
| -------- | ------------------------------------------------------------- |
| Models   | Providers, and the default model when none is set yet         |
| Files    | Workspace notes such as `SOUL.md`, `USER.md`, and `MEMORY.md` |
| Skills   | That assistant's skills, except Hermes bundled skills         |
| MCP      | Custom MCP servers for the acting user                        |
| Channels | Matching channels on the expert, created **disabled**         |

A second run skips anything that already exists. `--overwrite` replaces workspace files, skills, and the default model. Providers, MCP servers, and channels are never overwritten. Channels stay disabled so the old assistant and Octop do not both answer the same bot. `--dry-run` writes nothing. The command exits with status 1 when any item fails.

## `octop cloud`

Import a local Tencent Cloud CLI login into the Workbench cloud-server store:

```bash
octop cloud import-tccli --profile default
```

The Workbench also writes `~/.tccli` when you authorize there. See [Cloud servers](/en/guide/guides/cloud-hosts.md).

## `octop user`

Every `octop user` subcommand writes the local database offline: `create`, `list`, `set-email`, `passwd`, `role`, `disable`, `delete`, and `reset-mfa`. There is **no** `login` subcommand and the CLI does not store a JWT in `cli_state.json`. Pin a default user with `octop config set-user`.

Password reset:

```bash
octop user passwd <username> --password <password>
```

Clear TOTP, passkeys, and recovery codes without changing the password:

```bash
octop user reset-mfa <username>
```

Full examples are in [Channels & cron: octop user](/en/cli/channel-cron-commands.md#octop-user).

## `octop clean`

Reset CLI state, or delete Octop data under `~/.octop` while keeping the install runtime. **Destructive** — read the help carefully before running.


```bash Clear CLI state only (keep data)
octop clean
```
```bash Delete data, keep venv/ and bin/
octop clean --all
```
```bash Skip the confirmation prompt
octop clean --all --yes
```


### Options

| Option      | Description                                                                |
| ----------- | -------------------------------------------------------------------------- |
| (default)   | Delete `~/.octop/cli_state.json` (pinned `default_user` / `default_agent`) |
| `--all`     | Delete Octop data under `~/.octop`. Keeps `venv/` and `bin/`               |
| `--yes`     | Skip the confirmation prompt                                               |
| `--dry-run` | Print paths without deleting                                               |


> **WARNING**
> 
> `octop clean --all` deletes the database, workspaces, and configuration. It keeps the installer runtime. Run `octop backup create` before using this command.
> 


***

## `octop config`

Inspect or edit `~/.octop/cli_state.json` (pinned default user and agent).


```bash Show current CLI state
octop config show
```
```bash Pin the default --user
octop config set-user admin
```


### Subcommands

| Subcommand | Description                 |
| ---------- | --------------------------- |
| `show`     | Print the current CLI state |
| `set-user` | Pin the default `--user`    |

***

## `octop completion`

Generate and install shell command completion.


```bash Dump a bash completion snippet
octop completion show --shell bash
```
```bash Dump a zsh completion snippet
octop completion show --shell zsh
```
```bash Append to ~/.zshrc or ~/.bashrc
octop completion install
```



> **TIP**
> 
> After running `octop completion install`, reopen your terminal or run `source ~/.zshrc` (or `source ~/.bashrc`) to enable completion.
> 


***

## `octop version`

Print the installed octop version. Equivalent to the global `-v, --version` flag.

```bash
octop version
```
