Deploy a Project

TL;DR

Register a remote Forge target, push an immutable version, and start it. Every published name@version is permanent — increment the version before each push. A successful push does not mean the project is running; verify with status.

Why this workflow exists

A strategy that runs on your laptop is useful for development. A strategy that runs on a server, survives restarts, and exposes operational data through an API is useful for trading.

The deploy workflow bridges these two worlds. It does five things:

  1. Reads your project identity (NAME and VERSION) from CMakeLists.txt.

  2. Rejects the operation if that version already exists — immutability check.

  3. Packages your source tree without local build output.

  4. Transfers the package over SSH to the Forge host.

  5. Compiles and registers the version on Forge, making it available for lifecycle commands.

Note

Forge compiles your project on the server, not on your laptop. This means the Forge host must have the same Aurum SDK version and C++23 toolchain that your project targets. A project that compiles locally but fails on Forge usually indicates a toolchain version mismatch.

Register the target

aurum remote add prod aurum@forge.example.com --default
aurum remote show prod

Use the SSH username, host, and port provided by the Forge administrator. Key authentication must work without an interactive password prompt.

Tip

Test the SSH connection before your first push: ssh aurum@forge.example.com aurum version. If this fails, aurum push will also fail. Resolve host-key, user-key, proxy, and port issues in your normal SSH configuration.

Push the version

From any directory, pass the project path and remote name explicitly:

aurum push ./signal-watch prod

Warning

A published name@version is immutable. Forge rejects a push that would overwrite an existing version. This is not a bug — it is the mechanism that guarantees every deployment is auditable and every version is rollback-capable. Increment VERSION in CMakeLists.txt before each push.

Start and verify

aurum run signal-watch \
  --server prod \
  --version 0.0.1 \
  --wait

aurum status signal-watch --server prod
aurum logs signal-watch --server prod --tail

For a live venue account, add the credential reference expected by the Forge environment:

aurum run signal-watch --server prod --version 0.0.1 --auth okx-live

Credential material must already exist in the target’s secret store. push does not include local secrets.

Note

--wait blocks until the lifecycle operation converges or times out. Use --timeout-ms in automation to set a bounded wait. A successful --wait return means desired, process, and runtime states agree. Without --wait, the command acknowledges the operation but does not prove the project is ready.

Rollback

Stop the current version and start a previously registered version:

aurum stop signal-watch --server prod --version 0.0.2 --wait
aurum run signal-watch --server prod --version 0.0.1 --wait

Warning

Rollback requires that the previous version is still registered on Forge. Published versions are never automatically removed. If you cannot roll back, it means the version was never pushed or was explicitly unregistered. Keep at least one known-good version registered at all times.

Check Terminal after each transition; desired state, process state, runtime health, and data freshness are separate signals. A running process with a healthy runtime does not guarantee that market data is flowing — check the resource catalog for active resources.

Next steps