• 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 Management → App settings → App update uses the same rule unless you turn on pre-releases.

      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 user

      Every octop user subcommand writes the local SQLite database offline: create, list, set-email, passwd, role, disable, delete. 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>

      Full examples are in Channels & cron: octop user.

      octop clean

      Reset CLI state or wipe the entire ~/.octop/ tree. Destructive — read the help carefully before running.

      Clear CLI state only (keep data)
      Wipe the entire ~/.octop/ directory
      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)
      --allWipe the entire ~/.octop/ tree
      --yesSkip the confirmation prompt
      --dry-runPrint paths without deleting
      WARNING

      octop clean --all deletes the database, workspaces, and all configuration. 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