For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt, and this page is available as Markdown at /en/cli/server-commands.md.
  • English
  • 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.

    Interactive setup
    Non-interactive setup
    Interactive setup
    octop init

    Options

    OptionEnv varDescription
    --admin-username TEXTOCTOP_ADMIN_USERNAMEUsername for the first admin account
    --admin-password TEXTOCTOP_ADMIN_PASSWORDPassword for the first admin account
    --admin-display-name TEXTOCTOP_ADMIN_DISPLAY_NAMEDisplay 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.

    Default
    Custom host and port
    HTTPS with self-signed certificate
    HTTPS with your own certificate
    Default
    octop run

    Options

    OptionDefaultDescription
    --host TEXT127.0.0.1Bind host. Precedence: this flag > OCTOP_BIND_HOST > config.json > default
    --port INTEGER8088Listen port. Precedence: this flag > OCTOP_PORT > config.json > default
    --reload / --no-reloadoffEnable uvicorn auto-reload (development only)
    --ssl / --no-ssloffEnable HTTPS
    --certfile PATH—TLS certificate in PEM format
    --keyfile PATH—TLS private key in PEM format
    --log-levelinfoOne 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.

    Start (and install if missing)
    Stop
    Restart
    Check status and health
    Start (and install if missing)
    octop service start
    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.

    Check and install
    Check only, do not install
    Include pre-releases
    Check and install
    octop update

    Options

    OptionDescription
    --check / --no-checkReport the available version without installing
    --yes / -ySkip the confirmation prompt
    --verbose / -vPrint installer output
    --allow-prereleaseInclude 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.

    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 and Migrate from Hermes Agent.

    octop --agent <id> migrate openclaw --dry-run
    octop --agent <id> migrate hermes --from /srv/hermes --skip channels
    SourceWhat moves
    ModelsProviders, and the default model when none is set yet
    FilesWorkspace notes such as SOUL.md, USER.md, and MEMORY.md
    SkillsThat assistant's skills, except Hermes bundled skills
    MCPCustom MCP servers for the acting user
    ChannelsMatching 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:

    octop cloud import-tccli --profile default

    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:

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

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

    octop user reset-mfa <username>

    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.

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

    Options

    OptionDescription
    (default)Delete ~/.octop/cli_state.json (pinned default_user / default_agent)
    --allDelete Octop data under ~/.octop. Keeps venv/ and bin/
    --yesSkip the confirmation prompt
    --dry-runPrint 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).

    Show current CLI state
    Pin the default --user
    Show current CLI state
    octop config show

    Subcommands

    SubcommandDescription
    showPrint the current CLI state
    set-userPin the default --user

    octop completion

    Generate and install shell command completion.

    Dump a bash completion snippet
    Dump a zsh completion snippet
    Append to ~/.zshrc or ~/.bashrc
    Dump a bash completion snippet
    octop completion show --shell bash
    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.

    octop version