Your agents run 24/7, even when your laptop is closed.
Your hosted Actionist runtime. Agents, channels, schedules, and triggers you put in the cloud run here around the clock — even when your computer is off. The same Headless Runtime engine, two ways to host it.
Actionist’s Headless Runtime is the same engine regardless of where it runs. Choose hosted Cloud for zero infrastructure, or your own VPS for full control.
Hosted Cloud
Actionist provisions and manages the container. Your job is reading the status page. Schedules, triggers, Telegram, Slack — all fire when your computer is off. Requires a paid plan.
Self-hosted VPS
Any Linux server with SSH access. You supply the host; Actionist uploads the runtime bundle, writes the env, and starts the process. Full control over region, memory, and browser provider.
Run Locally
The Headless Runtime can also run as a local child process — useful for testing or for a machine that stays on. Schedules and channels stop when the app quits.
Both the hosted cloud and self-hosted VPS paths use the same Headless Runtime engine and expose the same capabilities: agents, skills, gateway, channels, schedules, triggers, MCP, marketplace, and more.
Click Cloud in the left sidebar (route /cloud-runtime) to see your hosted runtime’s current state, then click a state below to read exactly what it means, what the UI shows, and what — if anything — you need to do. The Cloud tab polls every 4 seconds while provisioning is in progress, then stops once the state is terminal; the runtime heartbeats every 30 seconds and is considered offline if no ping arrives within 90 seconds.
No runtime
Provisioning
Starting
Active
Ready
Heartbeat · every 30 s · stale after 90 s
“No cloud runtime yet”
Your hosted runtime provisions automatically once your subscription is active. This usually takes a couple of minutes. No action is needed — check back after subscribing. If your plan does not include a cloud runtime, the Cloud tab shows “Your plan doesn’t include a cloud runtime” with an Upgrade plan button. Clicking it opens a Stripe checkout in a new tab.
“Setting up your cloud runtime”
The RuntimeProvisioningStepper steps through four stages: Provisioning → Starting → Active → Ready. The page polls every 4 seconds. You can leave this page at any time — setup continues in the background.
“Setting up your cloud runtime” (Starting stage)
The container is launching. Still polling every 4 seconds. No action required. If Starting persists for more than several minutes, contact support.
“Your cloud runtime is active”
The runtime process is up and the Cloud tab is waiting for it to phone home. The runtime sends a heartbeat every 30 seconds; the backend considers it offline if no heartbeat arrives within 90 seconds. If this state persists for more than a few minutes, port 9090 may be blocked or outbound HTTP is firewalled — confirm port 9090 inbound and unrestricted outbound HTTP.
“Your cloud runtime is ready”
Agents and channels assigned to the cloud are running. The Runtime details card shows Plan, Region, Version, Browser, and Last heartbeat. The Connected channels card shows Telegram and Slack as Connected or Not connected. The runtime is healthy when status === ‘active’ and the last heartbeat is within the past 90 seconds.
Suspended state. Update your billing to resume. Your data is retained while suspended.
Failed state. Actionist retries automatically — Provisioning → retry. If the state persists, contact support.
Refresh button. Forces an immediate status poll at any time. Available in the top-right corner of the Cloud tab.
Once the runtime is ready, two cards appear below the status banner.
Runtime details
Shows Plan, Region, Version, Browser, and Last heartbeat timestamp. “Last heartbeat” tells you the last time the runtime phoned home. If it reads “Never”, the process has not yet sent its first ping.The runtime is considered healthy when status === 'active' and the last heartbeat is within the past 90 seconds.
Connected channels
Shows Telegram and Slack as Connected or Not connected. This card appears only once the runtime is ready — while provisioning, it shows “Waiting for your cloud runtime to be ready before channels can connect.”
The Refresh button in the top-right corner of the Cloud tab forces an immediate status poll at any time. Use it if you want confirmation without waiting for the next 4-second cycle.
If your plan does not include a cloud runtime, the Cloud tab shows “Your plan doesn’t include a cloud runtime” with an Upgrade plan button. Clicking it opens a Stripe checkout in a new tab. Once your subscription is active, the runtime provisions automatically — no further action needed.
On a paid plan, the hosted runtime provisions automatically, runs unattended, and restarts itself after a failed state. Your only interaction is the Cloud tab status page and, optionally, the Connected channels card.
Upgrade your plan
See what is included in each plan and upgrade directly from the billing page.
Once a VPS runtime is paired, you can migrate any locally-running agent — including its memory, skills, schedules, triggers, and channels — in a single click from the Agent Studio. Watch the preflight sequence below.
Move to VPS is available only in the Desktop app. The button does not appear in the web interface.
movedAgent Maya is now running on your paired VPS. Schedules, triggers, and channels transferred.
Open the agent in Agent Studio
In the desktop app, open Agents in the sidebar, then open the agent you want to move.
Click 'Move to VPS'
In the Agent Studio header, click Move to VPS. The dialog opens and immediately begins: “Checking agent, dependencies, channels, and memory…”
Review preflight results
The dialog shows up to three sections:
“Fix before moving” — blockers that must be resolved before migration can proceed.
“Warnings” — non-blocking items to review.
“What moves” — the transfer manifest.
If there are blockers, fix them in the agent’s settings, then click Re-check.
Review the transfer manifest
The “What moves” section lists everything that transfers to the VPS: Memory files, Skills, MCP servers, Schedules, Triggers, Channels.
Confirm the move
With no blockers, the Move to VPS button becomes active. Click it. After the move, this agent’s chat execution, memory, schedules, triggers, and channels run on your paired VPS.
Any Linux server with SSH access works. Actionist uploads the runtime bundle via SCP, installs dependencies, writes the environment file, and starts the process.
Open Settings → Headless Runtime
Go to Settings → Headless Runtime and select the Deploy to VPS mode (CloudArrowUp icon).
Fill in Connection
Enter your server’s Host (IP or hostname), Port (default: 22), Username, and SSH Private Key (click Choose… to pick a file from your machine).
Fill in Authentication
Enter your Anthropic API Key and optionally change the Claude Model (default: claude-sonnet-4-6-20250514). Set Health Port (default: 9090) and Files Port (default: 7783) if your server uses non-standard ports.
Fill in Telegram Gateway
Enter your Telegram Bot Token (required to enable the gateway). Optionally enter Allowed User IDs as a comma-separated list to restrict who can message the bot.
In production, always set Allowed User IDs. Without it, anyone who discovers the bot’s username can send it messages.
Test the connection
Click Test Connection to verify SSH reachability before deploying. A banner reads “SSH connection successful!” on success, or shows an inline error if the key or host is wrong.
Deploy
Click Deploy to VPS. If your organization already has an active paired runtime, a confirmation dialog appears:
“Replace existing paired runtime?”
“Your organization already has an active runtime. Deploying here will revoke it. Continue?”
Click Replace and deploy to proceed, or Cancel to keep the existing runtime.
Monitor the running runtime
Once running, three actions are available:
Check Status — polls the /healthz health endpoint on port 9090.
Logs — fetches the last 50 lines from runtime.log.
In builds where container deployment is enabled, you can choose how the runtime handles browser automation. Click a mode to see when to use it.
Hosted Cloud — the zero-ops path
Actionist provisions and manages the container for you. Your job is reading the status page on the Cloud tab. Schedules, triggers, Telegram, and Slack all fire when your computer is off. Auto-retries on failures. Requires an active paid plan — if your plan does not include cloud, the tab shows an Upgrade button.
Process mode — the simple VPS default
One node dist/index.cjs process per server. No container, no browser. Use process mode when your agents do not need web browsing — it is the simpler, lighter-weight option that most teams start with.
No browser
~120 MB container. Leanest option. Choose when agents do not need web browsing or screenshot-based computer use.
Use container mode (the third option) when you need strict isolation or explicit browser RAM control.
Container mode — browser provider choices
None (~120 MB)
No browser. Leanest container. Choose this when agents do not need web browsing or screenshot-based computer use.
Local Chrome (~1.5 GB)
Adds Chrome to the container for web tasks and screenshots. Idle stays near 120 MB; Chrome runs only during a task. Choose when you need browser automation and have sufficient RAM.
Browserbase (cloud)
Runs the browser off-box on Browserbase’s cloud. Container stays near ~1 GB. Browser tasks are metered and billed by Browserbase separately. Best for RAM-constrained VPS or low-traffic agents.
Enable container mode by checking Deploy as isolated container (multi-org) in the VPS form. Available in builds where container deployment is enabled.
Every runtime authenticates to the Actionist backend using a long-lived machine bearer token (mid_*). The first boot of a VPS runtime exchanges a one-time pairing code for this token and stores it at config/machine-token.json.
Copy immediatelySingle-use. Not shown again. If missed, generate a new one.
First bootPass as ACTIONIST_PAIRING_CODE env var. Runtime exchanges it for a mid_* token.
Token storedSaved to config/machine-token.json locally. Revoke via the Vault panel at any time.
Example pairing code (one-time)
ACTX-7F2A-K9R3Copy immediately — disappears after first use.
After exchange:ACTX-7F2A-K9R3→ mid_a7f2…k9r3 stored at config/machine-token.json
Open Machine Identities
Go to Settings → Credentials Vault → scroll to the Paired runtimes section. You will see all active mid_* machine identities and their live health state.
Generate a pairing code
Click Pair runtime, enter a label (for example, “VPS — Telegram bot”), then click Issue pairing code. A one-time code appears.
Copy the code immediately. It is single-use and will not be shown again. If you miss it, generate a new one — the old code is already expired.
Use the code on first boot
Pass the code to the VPS runtime as the ACTIONIST_PAIRING_CODE environment variable on first boot. The runtime exchanges it for a mid_* token and stores it locally.
Revoke if needed
To remove a machine identity, click Revoke next to it. Access is invalidated immediately — the VPS does not need to be online.
ActiveVPS — Telegram botmid_a7f2k9r3… · created Jun 10, 2026
Revoke
If your replace-existing-runtime confirmation dialog appears when deploying, it lists the current active identities. Confirm you are targeting the right server before clicking Replace and deploy — revoking the wrong identity cuts that server off immediately.
If you want Telegram bot connectivity without a remote server, the Headless Runtime can also run as a local child process — useful for testing or for machines that stay on.
Select Run Locally
Go to Settings → Headless Runtime and select Run Locally (Desktop icon).
Enter your Telegram Bot Token
Enter your Telegram Bot Token (required). Optionally add Allowed User IDs.
Start the runtime
Click Start Runtime. The badge cycles: Stopped → Starting… → Running (shows the process PID). Once connected, the Telegram logo appears with “Connected”.
Stop when done
Click Stop Runtime to kill the child process. Scheduled jobs and channels stop with it.
Run Locally keeps everything on your machine — it is not a replacement for hosted Cloud or a remote VPS. Schedules and channels stop running when you quit the app or click Stop Runtime.
The VPS runtime keeps a rolling log of everything it handled while you were away. Three things happened overnight — a scheduled digest fired, a webhook trigger came in, and a Telegram message got a reply — all without you.
The Cloud tab stepper reaches Ready only when status === ‘active’ AND the last heartbeat is within 90 seconds. For a self-hosted VPS runtime: if stuck at “Active” for more than a minute, port 9090 is likely blocked inbound (the health endpoint) or outbound HTTP from the VPS to the Actionist API is firewalled — open port 9090 inbound and confirm outbound HTTP is unrestricted. For a hosted cloud runtime stuck at “Active”, contact support.
Always restrict Telegram to known user IDs in production
Without Allowed User IDs set, anyone who discovers the bot’s username can message it. Set the Allowed User IDs field in the VPS form (or the TELEGRAM_ALLOWED_IDS environment variable). A comma-separated list of Telegram numeric user IDs is sufficient.
Test Connection before deploying
Always click Test Connection before hitting Deploy to VPS to confirm SSH reachability. This surfaces key-path and permission errors before the deployment attempt, saving you a failed deploy cycle.
Pairing codes are single-use and shown once
Generate the pairing code just before you need it. If you close the dialog without copying the code, generate a new one — the old code is already consumed. Each code becomes invalid immediately on first use.
Use Browserbase for RAM-constrained servers
Local Chrome raises the container memory ceiling to approximately 1.5 GB. Browserbase keeps the container near 1 GB by offloading browser work off-box. For low-traffic agents or VPS instances with under 2 GB of RAM, Browserbase is the safer choice — just account for per-task metered billing.
Enable vector memory search with a Gemini API key
On VPS, set the GEMINI_API_KEY environment variable to enable vector-backed memory search. Without it, the runtime falls back to full-text search only, which reduces the quality of memory recall for agents with large memory stores.
File proxy requires HTTPS in production
To enable web-based file browsing from the VPS, fill in both Public base URL and File proxy secret. The base URL must be HTTPS — the backend rejects plain HTTP outside of local development. The secret must match ACTIONIST_VPS_FILE_PROXY_SECRET on the backend.
Revoke compromised machine identities immediately
Go to Settings → Credentials Vault → Paired runtimes → Revoke. Revocation is immediate and does not require the VPS to be online. The mid_* token is invalidated at the backend; the next request from the runtime will fail authentication.
Schedule failures retry automatically
Failed schedule runs on VPS retry up to 3 times. The delays follow an exponential backoff: 30 s → 60 s → 120 s → capped at 300 s. Execution rows older than 7 days are pruned automatically. If you notice missed runs, check the Schedule tab for the run history.
Leave the provisioning page freely
Once provisioning starts, setup continues in the background. The page itself says “You can leave this page — setup continues in the background.” Come back when you want to check progress.
