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.
An agent is not just its instructions. Wherever it runs, it needs its memory, skills, MCP servers, schedules, triggers, and channels to come along. The sequence below shows what that inventory looks like.
There is no “Move to VPS” button, and you are not expected to move agents by hand. Placement is handled for you: agents created in the web app are already cloud-ready. Ignore any older instruction to migrate an agent yourself, and check the runtime label on the agent itself if you want to know where it is running.
Everything the agent has learned and every skill enabled on it stay attached to the agent, not to a machine.
Recurring runs and incoming triggers belong to the agent, so they keep firing wherever it runs.
A connected Telegram bot or Slack presence follows the agent. You do not reconnect it because placement changed.
If you want to know where an agent is running right now, check its runtime label on the agent itself, or open Settings → Cloud Runtime.
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 API Key. 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 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.
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
Machine identities are managed by the platform. There is no Paired runtimes panel in the Credentials Vault to browse them from, so treat identity handling as something the platform does on your behalf rather than a screen you visit.
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.
machine identity · illustrativePair runtime
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.
Before you start. You need the Headless Runtime section in Settings, which is not present in every workspace, and a Telegram bot token from @BotFather. If Settings has no Headless Runtime section, this mode is not available to you and the rest of this section does not apply.
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
On VPS, vector-backed memory search can be enabled with additional configuration. Without it, memory search uses full-text 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
There is no Paired runtimes panel in the Credentials Vault, so revocation is not a self-service action today. Contact the team if you need a runtime’s access cut off.
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.
