Skip to main content
ALWAYS ON

​
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.

The idea

​
One engine, two places to run 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.
Hosted cloud

​
The runtime lifecycle, state by state.

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.
Cloud Runtime · lifecycle states
Provisioning
Setting up your cloud runtime
ProvisioningStartingActiveReady
Active · awaiting heartbeat
Waiting for runtime to phone home
ActiveLast heartbeat: never
Heartbeat expected every 30 s
Ready
ReadyYour cloud runtime is ready
PlanPro
Regionus-east-1
Last heartbeat12 s ago
Suspended
SuspendedUpdate your billing to resume
Your data is retained while suspended
Upgrade plan
Ready state

​
Reading the details and channels cards.

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.
Cloud Runtime · ready stateRefresh
ReadyYour cloud runtime is ready
Runtime details
PlanPro
Regionus-east-1
Version2.4.1
BrowserNone
Last heartbeat8 s ago
Connected channels
TGTelegramConnected
SLSlackNot connected
Plans

​
The hosted cloud requires a paid plan.

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.
Agent Studio

​
What moves with an agent.

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.
Self-hosted

​
Deploy the runtime to your own 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 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.
  • Logs: fetches the last 50 lines from runtime.log.
  • Stop: terminates the remote process.
Settings · Headless Runtime · Deploy to VPS
Connection
Host192.168.1.1
Port22
Usernameroot
SSH Private Key~/.ssh/id_ed25519Choose…
Authentication
API Key••••••••
Health Port9090
Files Port7783
Telegram Gateway
Bot Token1234567890:AAH…
Allowed User IDs123456789, 987654321
Test ConnectionDeploy to VPS
Deploy modes

​
Three ways to run. Pick the right one.

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.
Credentials Vault

​
Machine identities and pairing codes.

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.

Issue codeSettings → Credentials Vault → Pair runtime. One-time code generated.
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.
Local mode

​
Run the runtime on your desktop.

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.
Always on

​
While your laptop was closed.

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.

VPS Runtime · overnight log · Jun 11–12 2026
schedule · daily-digest · fired 02:00 UTC
02:00agent Maya · schedule daily-digest started
02:01read inbox  23 emails · 4 flagged · summary drafted
02:02sent digest  Telegram · 1 message · delivered
02:02schedule complete  0 errors · next run 02:00 tomorrow
trigger · webhook · new-lead · received 04:37 UTC
04:37agent Dario · trigger new-lead matched · 1 payload
04:38enriched lead  Northwind Supplies · added to CRM
04:38sent follow-up  personalised email · 1 recipient · delivered
channel · Telegram · inbound message · 07:14 UTC
07:14agent Maya · channel message received · @maya_actionist_bot
07:14replied  “Tuesday 10 AM is free — want me to block it?” · delivered

The runtime does not wait for you to wake up. Schedules fire, triggers respond, channels reply. The lid being closed is not a blocker.

Overnight log · VPS runtime · 3 events handled · 0 errors
Best practices

​
Tips for a reliable runtime.

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Reference

​
Defaults and limits.

4 sCloud tab poll interval (settling)
30 sHeartbeat send interval
90 sHeartbeat freshness threshold
22Default SSH port
9090Health port (healthz endpoint)
7783Files port
50 linesLogs fetched per call
5 GBMax workspace size
50 GBMax org size
30 daysArtifact retention
3Schedule retry attempts
7 daysSchedule execution row retention
~120 MBBrowser: None (container RAM)
~1.5 GBBrowser: Local Chrome (container RAM ceiling)
~1 GBBrowser: Browserbase (container RAM)
Always on

​
Your agents shouldn’t need you to be awake.

Upgrade to a paid plan and your hosted runtime provisions automatically. Agents, schedules, and channels run around the clock, without your laptop.

Open the DashboardView plans

Hosted or self-hosted: the same runtime engine, the same capabilities.
Heartbeats every 30 s · auto-retries on failure · 90 s freshness threshold.

Keep going

​
Next steps.

Agents

Open an agent in the studio to review its tools, skills, and approval mode.

Channels

Connect Telegram and Slack bots so agents respond where your team already is, even when your computer is off.

Schedules

Set up recurring jobs that fire headlessly on your cloud or VPS runtime.

Billing

Upgrade to a paid plan to provision your hosted cloud runtime.