Running on a VPS

The Candle Harness runs whole on a Linux server: the core, your agents and their engines, and the view, in a terminal you reach over SSH. Triggers, rules bots and code bots then keep watching and trading when your own computer is asleep (Triggers, Rules bots, Code bots).

There’s no separate server mode. You install it as on any Linux machine (Installing) and use it through tmux.

Start with a user of its own, not root. Make an unprivileged user on the server and install and run the Candle Harness as that user. As root, each agent’s engine, every code bot and the Build tab’s coding harness run as root too, and what holds them back is weaker for root. candle-harness doctor warns when it runs as root.

The Candle Harness in tmux

Start the Candle Harness inside tmux on the server, so it keeps running when you disconnect:

ssh you@your-server
tmux new -s candle
candle-harness

Detach with ctrl-b d. Reattach later with ssh you@your-server then tmux attach -t candle. Setup runs the first time, as on any machine: Candle’s sign-in is a code you approve in your own browser, and each engine’s sign-in runs in the Candle Harness’s pane (Getting started).

A server has no keychain, so setup stops at sign-in and offers two ways on:

Keep the owner sign-in off the server, the safer way: make each agent’s key on your own computer and add it here with candle-harness key add --agent <name> (Keys on a server).
Sign in here. The Candle CLI then keeps its sign-in in a file locked by a passphrase you choose, CANDLE_KEYRING_PASSPHRASE. Setup shows the export line to paste into your shell’s startup file in an editor (never typed at a prompt, where it would stay in your history), and chmod 600 for that file, so only you can read it. A passphrase in a startup file is readable by anything that runs as you.

Pop-out works in tmux as anywhere: ctrl-p puts a pane in a split of its own (Make it yours).

The Build tab works over SSH too. Your coding harness signs in by a link and a code you open in your own browser: The Build tab gives each one’s command. Your bots folder is on the server, so clone your bots there with git, or let the harness write them there.

A trigger that’s on, or a bot that’s running, keeps the core running after you quit the view. To start it again after the server restarts, install it as a service:

candle-harness service install

It’s a systemd user service (~/.config/systemd/user/candle-harness-core.service). It starts the core at login and restarts it only if it crashed. candle-harness stop ends it until the next login.
Switch lingering on, or the service stops when you log out of SSH: loginctl enable-linger $USER (it may need sudo). The Candle Harness never runs it for you; service install and candle-harness doctor say when it’s off.
The service carries PATH, CANDLE_HARNESS_HOME and LANG from the shell you install it from, and your proxy and certificate settings if they’re set. Never a key or a passphrase. Its PATH leaves out any entry that isn’t a full path (., or a relative folder), and service install says which it left out. The file is readable by you only, and service install prints it.
It logs to core.log in the Candle Harness’s state folder (~/.config/candle/harness/state/).
candle-harness service status says whether it’s installed and running, and whether the running core is the service’s or a view’s. candle-harness service uninstall stops it and removes the file, and keeps your triggers and bots.
Code bots run inside the service: the core starts each one that’s on, and a stop or restart of the service ends and starts them with it.

Open the view in tmux at any time: it attaches to the service’s core.

On a Mac that stays on, the same command installs a LaunchAgent, and keep-awake keeps the Mac from sleeping while a trigger or bot is on (Triggers).

Keys on a server

Your agents’ keys are the Candle Harness’s own. Each is kept in the Candle Harness’s state folder, readable by your user only, and handed to each candle command the core runs. Don’t set the CLI’s CANDLE_API_KEY for the Candle Harness: it never needs it, and the Candle Harness leaves it out of everything it runs.

Keep the owner sign-in off the server. That’s Candle’s own advice for an always-on box. Make each agent’s key on your own computer and add it on the server with candle-harness key add --agent <name>, which reads it from a hidden prompt. Owner steps (making keys, the vault, sends) then run on your own computer, not the server.
Agent keys are Write keys: they trade, and can’t send funds out. With the owner sign-in kept off it, a server that’s taken holds only those keys: whoever has them can trade up to Candle’s caps on each key. The Candle Harness’s own limits hold what runs through its core, not someone using a key file directly. So set Candle’s caps on every key before you leave triggers or bots running (Limits).
If you sign the Candle CLI in on the server, a server that’s taken can also do what the owner can: make keys, change a wallet’s access, and approve a TEE wallet’s signer for the box. The passphrase for the CLI’s sign-in file sits in your startup file, where anything running as you can read it.

TEE wallets on a server

The embedded wallet trades from a server as it does anywhere: Candle signs, and nothing on the server holds a signer.

A TEE wallet’s trades run your own candle CLI on the server, which needs that wallet’s key signer on the server, in the CLI’s secret store there. Candle’s Run a bot on a headless machine covers it: making the signer on the box, approving it from your own machine, and where it’s stored.

Under the login service, the core has no CANDLE_KEYRING_PASSPHRASE, so the CLI can’t open its file store, and a TEE wallet’s trades are refused in the CLI’s words. On a server, trade from the embedded wallet, or run the core in tmux, with candle-harness core, from a shell that has the passphrase. Never put the passphrase in the service’s file. candle-harness doctor, run from a shell that has the passphrase, warns while the service is installed.

Notifications from a server

With the view open in tmux, while you’re attached, the Candle Harness sends your terminal’s own notification over SSH, where your terminal shows them, else the bell (Triggers).
With no view open, or while you’re detached, nothing reaches you. A trigger that asks you each time then expires its card unpressed, so on a server, give triggers a wallet that trades inside limits, or use notify and check back. A bot’s buys that would ask you are skipped the same way; its exits sell without a card.
From a script on the server, candle-harness cards --wait says how each waiting card ended, and candle-harness ask --json gives an agent’s reply and its cards as one object (Triggers). Neither approves anything.
Notifications into Quant, Candle’s Telegram bot, come once Candle opens the route.

The note when you reattach says what happened while you were away (While you were away).

Checking it

candle-harness doctor, on the server, names each trigger that’s on and what it watches, each bot and what it holds, whether a core is running and what holds it up, the service and lingering, and what can reach you with no window open.