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.
Options
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.
Options
Do not use --reload in production. Auto-reload restarts the process on every file change and is intended for local development only.
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.
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.
Options
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.
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 and Migrate from Hermes Agent.
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:
The Workbench also writes ~/.tccli when you authorize there. See Cloud servers.
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:
Clear TOTP, passkeys, and recovery codes without changing the password:
Full examples are in Channels & cron: 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.
Options
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).
Subcommands
octop completion
Generate and install shell command completion.
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.

