Short answer: Run claude -p "your prompt" on a remote computer: a VPS, a sandbox, or a Mac mini that stays on. -p runs Claude Code headless, with no UI, and you control which tools it can use and how it handles permissions through flags. To make it work in the cloud, you also have to set up that machine yourself: install Claude Code, log in with your Claude subscription or an API key, and authenticate every MCP server. If you'd rather skip that setup, fl0w gives every user their own cloud computer with your connectors and skills already synced, and turns a session into a scheduled workflow with one slash command.
Why run Claude Code headless?
You run Claude Code headlessly, without a UI, when you have a prompt you've tested once or twice and want to run over and over again.
Maybe you don't want it taking up a terminal. Maybe you want it running in the background on a schedule, or on a remote computer so you don't need to keep your laptop open.
Good candidates for headless Claude Code:
- A weekly changelog or docs-drift check against a repo
- A daily digest that summarizes new issues, PRs, or messages
- A prompt you trigger from CI, cron, or a webhook
- Anything you've already run interactively and just want to repeat (see turning a session into an automation)
How to run Claude Code headless in the cloud
Step 1: Pick a remote computer
Headless only helps if the computer stays on. Your laptop sleeps, so pick something that doesn't: a VPS, a cloud sandbox, or an always-on machine at home. See Can Claude Code run while my laptop is closed? for the trade-offs.
Step 2: Install and authenticate Claude Code on it
Install Claude Code on the remote box, then authenticate it with your Claude subscription or an API key. There's no browser on a headless server, so the usual options are:
# Option A: generate a long-lived token from your Claude subscription (run on your laptop)
claude setup-token
# then on the server
export CLAUDE_CODE_OAUTH_TOKEN=...
# Option B: use an Anthropic API key (billed per token)
export ANTHROPIC_API_KEY=...Do the same for every MCP server the prompt needs. Those tokens expire, so plan for that too: see How do I keep OAuth tokens working for an unattended AI agent?
Step 3: Run your prompt with claude -p
claude -p takes your prompt plus a lot of configuration options: whether to skip tool permissions, which tools to auto-allow, and which tools to expose at all.
cd ~/code/my-repo && claude -p "Review commits since yesterday and draft changelog entries in CHANGELOG.md" \
--allowedTools "Read,Edit,Bash(git log:*),Bash(git diff:*)" \
--output-format stream-json --verbose \
>> ~/logs/changelog.jsonl 2>&1The flags you'll reach for most:
| Flag | What it does |
|---|---|
-p, --print | Run one prompt non-interactively and exit |
--allowedTools | Tools that run without asking for permission |
--disallowedTools | Tools the agent can't use at all |
--permission-mode | How to handle anything not pre-approved |
--mcp-config | Load MCP servers from a JSON file |
--max-turns | Cap how many agent turns a run can take |
--output-format | text, json, or stream-json |
It's very configurable, which is great.
Step 4: Schedule it
Once the command works, put it in crontab, systemd, or GitHub Actions on the remote machine. How do I run Claude Code on a schedule? walks through each.
The limitations of headless Claude Code
Here's why I don't use it remotely myself:
- The command isn't the prettiest thing. Look at the CLI reference: unless you write these commands a lot, you have to figure out what all the flags and parameters mean.
- The output is hard to read. It's streaming JSON. If you've tested the prompt a couple of times, you probably won't need to read it much. But when something breaks at 3am, you'll be digging through JSON lines.
- You own the machine. You have to make sure the VPS or sandbox has everything it needs: your Claude Code subscription, your MCP tokens, your skills, your repos. And you have to keep it that way as you change things locally.
Why fl0w
fl0w is an alternative to running Claude Code headlessly: a harness built for automation and AI workflows.
- Sessions become workflows. Once you know you want a workflow out of a session, almost like a prompt template, you run one slash command,
/generate, to create it. It then runs automatically on your fl0w cloud computer on a schedule, from a webhook, or from a form. See turning a session into an automation. - Every user gets their own cloud computer. When you sign up for fl0w, you get a cloud computer for your fl0w agent to run on. It's not a sandbox that disappears after each run. It's yours, and it's still there between sessions.
- Your setup syncs automatically. The harness syncs your connectors and your skills, so there's no re-authenticating on a server, and a daily job keeps your MCP tokens fresh. See MCP servers in the cloud.
- The file system persists. You can create workflows that rely on files sticking around. For example, an automation that uses two different codebases plus a folder where you keep all your Markdown documents.
- Readable runs. Each workflow run shows its steps, logs, and outcome in the Automate tab in the browser instead of a JSON log file.
- A headless CLI when you want one. If you still want to drive it from your own CI or cron,
fl0w workflow <id>runs a saved workflow without the TUI. See headless commands.
curl -fsSL https://raw.githubusercontent.com/jackmuva/fl0w/main/install.sh | bash
fl0w loginThe Quickstart walks through the rest.
One honest caveat: fl0w is its own harness, not the claude binary. You can use Claude models with it, and it can load the skills you've installed for Claude Code. If you need Claude Code specifically, run claude -p on a VPS or sandbox. If you want the work to run in the cloud without the setup, try fl0w and see how having your own remote computer works.
Headless Claude Code vs. fl0w
claude -p on a VPS or sandbox | fl0w | |
|---|---|---|
| Runs with your laptop closed | Yes | Yes |
| Setup | Install, auth, MCP, and skills by hand | Sign up; connectors and skills sync |
| Scheduling | Your own cron, systemd, or CI | Built-in schedule, webhook, and form triggers |
| Creating a job | Write the command and flags | /generate from a session |
| Reading results | Streaming JSON logs | Run history in the browser |
| Persistent files | Yes, if the machine persists | Yes |
| Agent | Claude Code | fl0w harness with Claude models |
FAQ
What is Claude Code headless mode?
Headless mode is running Claude Code non-interactively with claude -p "prompt". It runs the prompt, prints the result, and exits, so you can call it from scripts, cron, or CI.
How do I authenticate Claude Code on a headless server?
Run claude setup-token on a machine with a browser to create a long-lived token from your Claude subscription, then set it as CLAUDE_CODE_OAUTH_TOKEN on the server. Or set ANTHROPIC_API_KEY to bill usage to an API key instead.
How do I skip permission prompts in claude -p?
Pre-approve the tools the prompt needs with --allowedTools, block what it shouldn't touch with --disallowedTools, and set --permission-mode for everything else. Only skip permissions entirely inside an isolated sandbox.
Can I run headless Claude Code on a schedule?
Yes. Call claude -p from cron, systemd, launchd, or GitHub Actions on a machine that stays on. Your laptop stops running cron jobs when it sleeps.
What output formats does headless Claude Code support?
text (the default), json for a single result object, and stream-json for newline-delimited events as the run happens.
Is there an easier way to run Claude Code prompts in the cloud?
If you don't need the claude binary itself, fl0w gives you a personal cloud computer with your connectors and skills synced, and turns a session into a scheduled workflow with /generate.