How RemoteHangar works

Architecture

RemoteHangar is one Node.js service under systemd, with an SQLite database, on a Linux server you own. People use it through a web console that installs as an app on desktop and phone.

The unit of work is a bay: one agent session with its own working directory, its own HOME and its own task queue. A person can own many bays. Every agent turn starts a short-lived agent process inside a sandbox; the process calls the model provider you configure and runs its tools on your server.

Optionally, a small Go connector on another host of yours links it back over mutual TLS. Agents can then run file and shell tools on that host, and the console shows its terminal, logs and health.

The sandbox around each agent

Every agent process runs under bubblewrap. The system is mounted read-only apart from the writable exceptions listed below. Privilege escalation is blocked with NoNewPrivileges, so there is no sudo inside a bay.

The service itself runs under a hardened systemd unit: ProtectSystem=strict, ProtectHome=read-only and NoNewPrivileges.

Writes outside /home and the bay’s own directories are blocked. Reads are not yet isolated between bays: an agent can read files the service user can read, and /home is writable from every bay. Treat one installation as one trust group, typically one team. Read isolation is planned.

• Writable: the bay’s working directory and HOME, the whole /home directory (shared by every bay), the attachment and plugin caches and the agent memory directory
• Read-only: the rest of the file system, including the release and the data root
• Private per process: /tmp
• Optional: Docker inside bays, off by default. Enabling it gives bays the host’s Docker socket, which is root-equivalent on that host.

The task queue

Each bay has a queue and works through it one task at a time. A task is either a typed prompt or a ticket from YouTrack, Jira or Notion. People add tasks; RemoteHangar does not poll trackers on its own.

A task stays running across as many chat turns as the work needs. It finishes when the agent marks it done or blocked, or when a person presses Done. A blocked task pauses the queue until someone looks at it. Stopping a running turn puts the task back in the queue.

Queue turns always run as the bay’s owner, never as whoever added the task. Limits keep a queue sane: 10 new tasks per minute per user and 200 unfinished tasks per bay.

• queued: waiting for its turn
• running: the agent is working on it
• done: the agent or a person marked it complete
• blocked: the agent needs a person; the queue pauses
• error: the task or the bay failed; the queue pauses
• cancelled or skipped: a person moved past the task

Where your data lives

Everything is on your disk, in four standard locations. Workspaces live in the directories you allow at install time, /opt/repos and /home by default.

Public API

Pipelines and internal tools call agents through Public API v1, described in OpenAPI with Swagger UI on your server. Clients authenticate with bearer tokens that carry scopes and expire after 90 days by default; the server stores only their SHA-256 hashes.

Responses stream back as Server-Sent Events. A one-shot request can require output that matches a JSON schema: in strict mode RemoteHangar validates the answer and retries up to three times. Requests can carry an idempotency key, set effort and a token budget, and attach files by URL. Limits apply per API token and per host, and turns end on three kinds of timeout: total time, time to the first event and silence.

Sessions are long-lived bays you can prompt, interrupt and download files from. A one-shot request creates a throwaway bay, runs one prompt and removes the bay afterwards:

curl -N https://hangar.example.com/v1/oneshot \
  -H "Authorization: Bearer $HANGAR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Summarize why the tests in this log fail",
    "idempotency_key": "ci-run-4812",
    "effort": "low",
    "response_format": {
      "type": "json_schema",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": { "summary": { "type": "string" } },
        "required": ["summary"]
      }
    }
  }'

Updates and rollback

A systemd timer runs the updater. It installs a new release only inside your maintenance window and only after checking twice that no agent is busy. You can pin a version, choose the release channel or turn automatic updates off.

Each release manifest is signed with minisign; the signing key never sits on the distribution server. If the host cannot run the verifier, the installer only warns; --require-signature makes the check mandatory. Before an update the database is snapshotted. If the new version fails its health check, both code and database schema roll back automatically.

If a published release turns out to be bad, we move the channel pointer back to the previous version, so servers that have not updated yet never take it.

Requirements

RemoteHangar targets Ubuntu 22.04 on x86_64. The installer needs root; the service runs as its own unprivileged user.

• OS: Ubuntu 22.04 with systemd. Ubuntu 24.04 blocks the unprivileged user namespaces the sandbox needs.
• CPU: x86_64
• Memory: about 350 MB per concurrent agent turn, on top of the base service. The default 3 GB limit fits four concurrent turns.
• Disk: about 250 MB to download per release and more once unpacked (earlier versions are kept for rollback), plus several hundred MB for optional components (code search, browsers for UI tests), plus your repositories
• Network: outbound HTTPS to your model provider, directly or through your corporate proxy
• Optional: nginx with a Let’s Encrypt certificate, set up by the installer