APIThe local API

RoachNet 1.1 runs one native helper, roachnet-runtime. It gives the app a loopback API, your phone a token-gated bridge, the installer a setup service, and every Ollama, OpenAI or Anthropic client a model server. All four listen on 127.0.0.1 and nowhere else.

macOS 1.1.4167 routes · 16 groupsMatches RoachNet 1.1.4
On this page

Four servers on your Mac

Loopback APIfresh port each launch

The app's own API.

Model server:36434

RoachInference.

Companion bridge:38111

What your phone talks to.

Setup serviceephemeral port

The installer backend.

ServerWhereAuth
Loopback API127.0.0.1, a fresh port each launch. Find the port and token shows how to read it.When RoachNet.app started the runtime: authorization: Bearer <token> (or x-roachnet-api-token) with the launch token from native-server-info.json, or a RoachClaw API token (rn_…) whose scope covers the route. GET /api/health needs none. Loopback Host only; JSON bodies must be sent as application/json, or you get a 415.
Model server127.0.0.1:36434. RoachNet.app always uses it; OLLAMA_BASE_URL moves it for a runtime you start yourself.No token, like Ollama. Loopback Host only, and an Origin header must be a loopback, app://, file://, tauri:// or vscode-webview:// origin. Bodies may be sent without a JSON content type, as Ollama clients do.
Companion bridge127.0.0.1:38111 by default, or your RoachTail relay hostauthorization: Bearer <companion token> or a paired device’s rtp_ token. The same routes also answer on the loopback API without one.
Setup service127.0.0.1, ephemeral port (set ROACHNET_SETUP_PORT to pin it)No token. Loopback Host header only; JSON bodies must be sent as application/json.

Examples on these pages use $ROACHNET, $MODELS, $BRIDGE and $SETUP for these four addresses.

Since 1.1.4 the Org has a fifth listener of its own, the webhook door: 127.0.0.1:38117 unless you choose another port, and only while you have it open. It answers one route, a routine's signed webhook.

Find the port and token

When RoachNet.app starts the runtime, it picks a fresh port and writes the address to a file only your account can read. It also gives the runtime a fresh launch token. Since 1.1.3 that token goes to the runtime on its standard input and stays in memory, so it's in no file and no environment variable. To call the API yourself, make a RoachClaw API token in Settings › RoachClaw. It survives restarts, you choose its scope, and you can revoke it. RoachNet shows the token once and keeps only its SHA-256. These lines set $ROACHNET and $TOKEN:

Terminal
# the runtime state file RoachNet.app writes at launch
INFO=~/RoachNet/storage/state/runtime-state/native-server-info.json
ROACHNET=$(sed -n 's/.*"webUrl" *: *"\([^"]*\)".*/\1/p' "$INFO")
TOKEN=rn_…   # the RoachClaw API token you made, with the read scope

curl -s "$ROACHNET/api/system/info" -H "authorization: Bearer $TOKEN"
{"cpu":{…},"mem":{…},"os":{…},"hardwareProfile":{"memoryTier":"balanced","recommendedModelClass":"7b",…}}

GET /api/health needs no token, so it's a quick way to check that the runtime is up.

Scope What it opens
chat The chat routes. New tokens get this scope unless you choose another.
read Every GET route
admin Everything

Send it the same way, as authorization: Bearer rn_…. A token without the scope a route needs gets a 403 that names the scope.

House rules

401 · 403Token, since 1.1

When RoachNet.app started the runtime, every route except GET /api/health wants the launch token or a RoachClaw API token: 401 without one, 403 when a token lacks the scope. Org calls that bring their own x-roachnet-org-key skip it. A runtime you start yourself asks for no token unless you set ROACHNET_API_TOKEN.

HostLoopback only

A Host header that isn't a loopback name gets a 403, so a page using DNS rebinding can't read your Mac. A request whose Origin is another website gets a 403 too.

415JSON means JSON

The loopback API takes bodies only as content-type: application/json. Anything else gets a 415; that's what stops a web page from posting a form at it.

1 MB · 2 MBSmall bodies

Request bodies are capped at 1 MB on the loopback API and 2 MB through the companion bridge. Errors come back as { "error": "…" } with a real status code.

The model server follows Ollama's rules instead: no token and no JSON content type required, and errors in each API's own shape. See Model server.

Routes

Every route the five servers answer, plus the two functions roachnet.org runs, from the same route data as the route browser. Type to filter; the browser has the request bodies, responses, source lines and a curl you can paste for each.

167 routes
  • GET/api/stateSetup service
    Installer state
  • POST/api/configSetup service
    Save installer choices
  • POST/api/installSetup service
    Start the install
  • POST/api/launchSetup service
    Open RoachNet
  • POST/api/container-runtime/startSetup service
    Container runtime (retired)
  • GET/api/healthSetup service
    Setup health
  • GET/api/healthSystem
    Runtime health
  • GET/api/system/internet-statusSystem
    Internet check
  • GET/api/system/infoSystem
    Hardware profile
  • GET/api/system/servicesSystem
    Service list
  • POST/api/system/services/installSystem
    Install a service
  • POST/api/system/services/affectSystem
    Start or stop a service
  • GET/api/system/ai/providersSystem
    AI providers
  • GET/api/system/latest-versionSystem
    Check for an update
  • POST/api/system/updateSystem
    Download the update
  • GET/api/system/update/statusSystem
    Update progress
  • GET/api/ollama/installed-modelsModels and chat
    Installed models
  • POST/api/ollama/chatModels and chat
    Chat with a local model
  • POST/api/roachclaw/applyModels and chat
    Pull a model
  • GET/api/roachclaw/modelsModels and chat
    Model library
  • POST/api/roachclaw/models/pullModels and chat
    Download a library model
  • POST/api/roachclaw/models/stopModels and chat
    Stop a model download
  • GET/api/openclaw/skills/installedModels and chat
    OpenClaw skills
  • POST/api/chatModel server
    Chat (Ollama)
  • POST/api/generateModel server
    Generate (Ollama)
  • POST/api/embedModel server
    Embeddings (Ollama)
  • POST/api/createModel server
    Make a model
  • POST/api/showModel server
    Model details
  • GET/api/psModel server
    Loaded models
  • GET/api/tagsModel server
    Installed models
  • POST/api/pullModel server
    Pull a model
  • POST/api/copyModel server
    Copy a model
  • DELETE/api/deleteModel server
    Delete a model
  • POST/v1/chat/completionsModel server
    Chat completions (OpenAI)
  • POST/v1/completionsModel server
    Completions (OpenAI)
  • POST/v1/responsesModel server
    Responses (OpenAI)
  • POST/v1/embeddingsModel server
    Embeddings (OpenAI)
  • GET/v1/modelsModel server
    Models (OpenAI)
  • POST/v1/messagesModel server
    Messages (Anthropic)
  • POST/v1/messages/count_tokensModel server
    Count tokens (Anthropic)
  • GET/api/clusterRoachNet Cluster
    Cluster status
  • PUT/api/clusterRoachNet Cluster
    Change cluster settings
  • GET/api/cluster/nearbyRoachNet Cluster
    Macs nearby
  • POST/api/cluster/peersRoachNet Cluster
    Add a Mac
  • GET/api/tracesRoachTrace
    Traces
  • GET/api/traces/metricsRoachTrace
    Trace totals
  • GET/api/traces/:idRoachTrace
    One trace
  • POST/api/traces/:id/scoresRoachTrace
    Score a trace
  • GET/api/traces/settingsRoachTrace
    Tracing settings
  • POST/api/traces/export/testRoachTrace
    Test the export
  • GET/api/roachclaw/statusRoachClaw agent
    RoachClaw status
  • GET/api/roachclaw/readinessRoachClaw agent
    Readiness
  • GET/api/roachclaw/agent/statusRoachClaw agent
    Agent status
  • POST/api/roachclaw/agent/runRoachClaw agent
    Plan an agent run
  • GET/api/roachclaw/operationsRoachClaw agent
    Operations snapshot
  • GET/api/roachclaw/diagnostics/servicesRoachClaw agent
    Service health report
  • GET/api/roachclaw/scoped-tools/capabilitiesRoachClaw agent
    Scoped tool bridge
  • GET/api/roachclaw/workspace/browseRoachClaw agent
    Browse folders
  • GET/api/roachclaw/tool-policyRoachClaw agent
    Tool policy
  • POST/api/roachclaw/tool-policyRoachClaw agent
    Save disabled tools
  • POST/api/roachclaw/tool-policy/evaluateRoachClaw agent
    Evaluate a turn
  • GET/api/roachclaw/context-budgetRoachClaw agent
    Context budget
  • POST/api/roachclaw/context-budgetRoachClaw agent
    Set the context budget
  • POST/api/roachclaw/url-safety/checkRoachClaw agent
    Check an outbound URL
  • GET/api/roachclaw/user-timeRoachClaw agent
    User time
  • POST/api/roachclaw/user-timeRoachClaw agent
    Set user time
  • GET/api/roachclaw/subscriptionsRoachClaw keys and lanes
    Plan models
  • PUT/api/roachclaw/subscriptionsRoachClaw keys and lanes
    Turn plan models on or off
  • GET/api/roachclaw/cloud-providersRoachClaw keys and lanes
    Cloud provider keys
  • POST/api/roachclaw/cloud-providersRoachClaw keys and lanes
    Save a provider key
  • DELETE/api/roachclaw/cloud-providers/:providerRoachClaw keys and lanes
    Remove a provider key
  • GET/api/roachclaw/tokensRoachClaw keys and lanes
    API tokens
  • POST/api/roachclaw/tokensRoachClaw keys and lanes
    Issue an API token
  • DELETE/api/roachclaw/tokens/:idRoachClaw keys and lanes
    Revoke an API token
  • GET/api/roachclaw/memory-providerRoachClaw keys and lanes
    Memory providers
  • POST/api/roachclaw/memory-providerRoachClaw keys and lanes
    Add a memory provider
  • GET/api/roachclaw/provider-oauthRoachClaw keys and lanes
    Provider OAuth flows
  • POST/api/roachclaw/provider-oauthRoachClaw keys and lanes
    Record an OAuth flow
  • GET/api/roachclaw/embedding-lanesRoachClaw keys and lanes
    Embedding lanes
  • POST/api/roachclaw/embedding-lanesRoachClaw keys and lanes
    Configure the custom lane
  • GET/api/roachclaw/security/tls-overridesRoachClaw keys and lanes
    TLS CA bundle
  • POST/api/roachclaw/security/tls-overridesRoachClaw keys and lanes
    Set a CA bundle
  • GET/api/roachclaw/security/upload-limitsRoachClaw keys and lanes
    Upload limits
  • GET/api/roachclaw/migration-document-toolsRoachClaw keys and lanes
    Migration and document tools
  • GET/api/roachclaw/:collectionRoachClaw stores
    List a store
  • POST/api/roachclaw/:collectionRoachClaw stores
    Create or update an item
  • DELETE/api/roachclaw/:collection/:idRoachClaw stores
    Delete an item
  • GET/api/roachclaw/mailRoachClaw stores
    Mail store
  • POST/api/roachclaw/mail/messagesRoachClaw stores
    Save a message
  • POST/api/roachclaw/mail/draftsRoachClaw stores
    Save a draft
  • DELETE/api/roachclaw/mail/messages/:idRoachClaw stores
    Delete a message
  • DELETE/api/roachclaw/mail/drafts/:idRoachClaw stores
    Delete a draft
  • GET/api/roachclaw/cookbook/schedulesRoachClaw stores
    Model serve schedules
  • POST/api/roachclaw/cookbook/schedulesRoachClaw stores
    Save a serve schedule
  • DELETE/api/roachclaw/cookbook/schedules/:idRoachClaw stores
    Delete a serve schedule
  • POST/api/roachclaw/cookbook/progress-signalRoachClaw stores
    Progress signal
  • GET/api/roachclaw/backupsRoachClaw stores
    Backup snapshots
  • POST/api/roachclaw/backupsRoachClaw stores
    Take a backup
  • DELETE/api/roachclaw/backups/:idRoachClaw stores
    Delete a snapshot record
  • GET/api/roachclaw/exportRoachClaw stores
    Export everything
  • GET/api/maps/curated-collectionsMaps, library and speech
    Map collections
  • POST/api/maps/download-base-assetsMaps, library and speech
    Prepare map folders
  • POST/api/maps/download-collectionMaps, library and speech
    Download a map collection
  • POST/api/maps/download-remoteMaps, library and speech
    Download a map by URL
  • GET/api/zim/curated-categoriesMaps, library and speech
    Library categories
  • POST/api/zim/download-category-tierMaps, library and speech
    Download a library tier
  • POST/api/zim/download-category-resourceMaps, library and speech
    Download one library item
  • POST/api/zim/download-remoteMaps, library and speech
    Download a ZIM by URL
  • GET/api/zim/wikipediaMaps, library and speech
    Wikipedia options
  • POST/api/zim/wikipedia/selectMaps, library and speech
    Pick a Wikipedia build
  • GET/api/site-archivesMaps, library and speech
    Saved sites
  • GET/api/rag/filesMaps, library and speech
    Vault files
  • GET/api/roachspeech/model-packsMaps, library and speech
    RoachSpeech packs
  • POST/api/roachspeech/model-packs/downloadMaps, library and speech
    Install a RoachSpeech pack
  • GET/api/collectionsMaps, library and speech
    Live collections
  • GET/api/downloads/jobsDownloads and jobs
    Download jobs
  • DELETE/api/downloads/jobs/:jobIdDownloads and jobs
    Cancel or clear a job
  • GET/api/benchmark/statusDownloads and jobs
    Benchmark status
  • POST/api/benchmark/runDownloads and jobs
    Run a benchmark
  • GET/api/packsFeature packs
    Packs
  • GET/api/packs/:idFeature packs
    One pack
  • POST/api/packs/installFeature packs
    Install a pack
  • POST/api/packs/:id/:actionFeature packs
    Enable, disable or remove
  • GET/api/org/adaptersRoachClaw Org
    Agents on this Mac
  • POST/api/org/adapters/:kind/testRoachClaw Org
    Try an agent
  • GET/api/org/webhook-doorRoachClaw Org
    The webhook door
  • PUT/api/org/webhook-doorRoachClaw Org
    Open or shut the webhook door
  • GET/api/org/companiesRoachClaw Org
    Companies
  • POST/api/org/companiesRoachClaw Org
    Start a company
  • GET/api/org/companies/:cid/dashboardRoachClaw Org
    Dashboard
  • GET/api/org/companies/:cid/org-chartRoachClaw Org
    Org chart
  • GET/api/org/companies/:cid/agentsRoachClaw Org
    Agents
  • POST/api/org/companies/:cid/agentsRoachClaw Org
    Hire an agent
  • POST/api/org/companies/:cid/agents/:id/:actionRoachClaw Org
    Pause, resume or let go
  • GET/api/org/companies/:cid/issuesRoachClaw Org
    Issues
  • POST/api/org/companies/:cid/issuesRoachClaw Org
    File an issue
  • PATCH/api/org/companies/:cid/issues/:idRoachClaw Org
    Change an issue
  • POST/api/org/companies/:cid/issues/:id/commentsRoachClaw Org
    Comment on an issue
  • GET/api/org/companies/:cid/approvalsRoachClaw Org
    Approvals
  • POST/api/org/companies/:cid/approvals/:id/:decisionRoachClaw Org
    Decide an approval
  • GET/api/org/companies/:cid/budgetsRoachClaw Org
    Budgets
  • POST/api/org/companies/:cid/budgetsRoachClaw Org
    Set a budget
  • GET/api/org/companies/:cid/routinesRoachClaw Org
    Routines
  • POST/api/org/companies/:cid/routinesRoachClaw Org
    Add a routine
  • POST/api/org/companies/:cid/routines/:id/runRoachClaw Org
    Run a routine now
  • GET/healthCompanion bridge
    Bridge health
  • GET/api/companion/bootstrapCompanion bridge
    Phone bootstrap
  • GET/api/companion/runtimeCompanion bridge
    Runtime snapshot
  • GET/api/companion/vaultCompanion bridge
    Vault summary
  • GET/api/companion/accountCompanion bridge
    Account link
  • POST/api/companion/account/affectCompanion bridge
    Link or unlink the account
  • GET/api/companion/roachtailCompanion bridge
    RoachTail state
  • POST/api/companion/roachtail/pairCompanion bridge
    Pair a device
  • POST/api/companion/roachtail/affectCompanion bridge
    Change RoachTail
  • GET/api/companion/roachsyncCompanion bridge
    RoachSync state
  • POST/api/companion/roachsync/affectCompanion bridge
    Change RoachSync
  • POST/api/companion/installCompanion bridge
    Queue an install
  • GET/api/companion/chat/sessionsCompanion bridge
    Chat sessions
  • POST/api/companion/chat/sessionsCompanion bridge
    New chat session
  • GET/api/companion/chat/sessions/:idCompanion bridge
    One chat session
  • POST/api/companion/chat/sendCompanion bridge
    Send a chat message
  • POST/api/companion/services/affectCompanion bridge
    Control a service
  • POST/api/companion/*Companion bridge
    Any other companion action
  • GET/api/companion/themeCompanion bridge
    Active theme
  • POST/hooks/:addressWebhook door
    Call a routine’s webhook
  • POST/.netlify/functions/register-accountroachnet.org functions
    Create a website account
  • POST/.netlify/functions/roachclaw-chatroachnet.org functions
    Web RoachClaw message

RoachClaw on the web

RoachClaw on roachnet.org is the second of those two functions, POST /.netlify/functions/roachclaw-chat, and it answers only when you're signed in to a RoachNet account. Every reply it returns, and every message it keeps in your account, carries a provider and a model that say what answered:

provider What answered What the chat shows
RoachClaw local relay Your Mac. The function passed your message to your Mac's companion bridge, POST /api/companion/chat/send, and model is the model your Mac used. RoachClaw, on your Mac, with the model's name.
RoachBrain Cloud The hosted model, SmolLM2 135M, which runs on roachnet.org's servers. Nothing ran on your Mac. RoachClaw, hosted model, with the model's name.

Every reply is signed RoachClaw. The label after it only says where a reply ran when the stored values say so. Messages from before these two values existed show RoachClaw with no label. A hosted reply is never labeled as local.

A thread records the same thing in metadata.relay.kind, as local-device or roachbrain-cloud. These values don't change when the chat's wording does, so match on them in anything you write.

Checked against v1.1.4 · 5 November 2026
6 pages

Get started

13 pages

Guides

7 pages

Reference

5 pages

API

9 pages

Releases

1 page

Support

1 page

Design
esc
↑ ↓ move↵ openesc closeSearches on your device. Nothing is sent anywhere.