01
Start local
Claude gets its own isolated $HOME. No Postgres or Docker required.
terminal
export ANTHROPIC_API_KEY='sk-ant-...'
npx openeral
Isolated home directory, PostgreSQL-backed workspace state, and StringCost metering for agent runs. No Docker. No SDK rewrite.
Start here
Local sandbox, then optional metering + persistence
export ANTHROPIC_API_KEY='sk-ant-...'
npx openeral
# Optional: meter usage
export STRINGCOST_API_KEY='sk-stringcost-...'
# Optional: persist files
export DATABASE_URL='postgresql://user:pass@host:5432/db'
export OPENERAL_WORKSPACE_ID='project-alpha'
npx openeral
1 command
start local
0 SDK changes
drop-in CLI
Postgres
persistent home
StringCost
metered egress
Start with just an API key. Add metering, persistence, and workspace isolation only when you need them.
01
Claude gets its own isolated $HOME. No Postgres or Docker required.
export ANTHROPIC_API_KEY='sk-ant-...'
npx openeral
02
Set one StringCost key and every Anthropic call is tracked by session and workspace.
export STRINGCOST_API_KEY='sk-stringcost-...'
npx openeral
03
Add Postgres when you want files to survive after the session ends.
export DATABASE_URL='postgresql://user:pass@host:5432/db'
npx openeral
04
Use the same workspace ID to restore the same files next session.
export OPENERAL_WORKSPACE_ID='project-alpha'
npx openeral
local-first
starts without Postgres
1 env var
StringCost metering
workspace
persistent home
pg
database from bash
$HOME points at an OpenEral workspace, not your real laptop home.
$HOME=/tmp/openeral-<workspace-id>Workspace files restore on startup and sync back while the agent works.
Claude can run pg queries directly from its sandboxed shell.
Anthropic calls route through StringCost when the API key exists.
Claude can inspect session spend, set task limits, and warn mid-run.
Different workspace IDs produce different state and attribution boundaries.
Regenerate project memory around fresh workspace context.
Claude Code
agent runtime
/home/agent
isolated workspace
PostgreSQL
optional persistence
StringCost
optional metering
Start with Anthropic. Add StringCost and Postgres when ready.
ANTHROPIC_API_KEYClaude Code provider key
requiredSTRINGCOST_API_KEYTurns on proxy metering
optionalDATABASE_URLTurns on persistence + pg access
optionalOPENERAL_WORKSPACE_IDNames the persistent workspace
optionalANTHROPIC_API_KEY='sk-ant-...'
STRINGCOST_API_KEY='sk-stringcost-...'
DATABASE_URL='postgresql://user:pass@host:5432/db'
OPENERAL_WORKSPACE_ID='project-alpha'
Same workspace ID means the same files come back. Claude can query Postgres from bash via pg.
Sync strategy: restore on session start, sync on write, final sync on exit.
echo "notes" > $HOME/notes.txt
cat $HOME/notes.txt
# Output: notes
pg "SELECT count(*) FROM users"
pg "\d public.orders"
Package a native OpenEral skill so the agent can inspect spend, set limits, and warn inside the conversation.
get_session_cost
current run spend
get_workspace_cost
project-level spend
set_budget_limit
warn or stop at threshold
get_recommendations
find expensive calls
"How much did this workspace spend today?"
"Warn me at $5 for this task. Stop at $8."
"Which calls in this session were expensive?"
presigned
API calls route through proxy
per-session
cost tracked per invocation
per-workspace
aggregate project spend
1 command
vs. 50+ lines of Docker config
Isolated home directory
PostgreSQL persistence
Database from bash
Automatic cost tracking
Session isolation
Zero-config start
The sandbox makes the safe path the default: isolated home, explicit secrets, auditable state.
SSH keys
Not mounted into agent home
Cloud credentials
Kept outside sandbox path
.env files
Passed through proxy, not filesystem
Git remotes
Explicit workspace policy required
Use the shell directly for custom agents. The TypeScript API wraps everything into a single createOpeneralShell call.
import { createOpeneralShell, createToolHandler } from 'openeral-js'
const shell = await createOpeneralShell({
connectionString: process.env.DATABASE_URL,
workspaceId: 'project-alpha',
})
const handleBash = createToolHandler(shell)
await shell.exec('echo "hello" > /home/agent/notes.txt')
await shell.exec('cat /home/agent/notes.txt')
No. Without DATABASE_URL, OpenEral runs with a local temp home directory. Add PostgreSQL when you need persistence.
Yes. The TypeScript API works with any agent that has bash access.
When STRINGCOST_API_KEY is set, OpenEral presigns your Anthropic key with StringCost and routes API calls through the proxy.
The agent continues working with local files. Sync resumes when the database reconnects.