AgentHTTP

AgentHTTP is the HTTP transport for a local Agent. It exposes the RemoteAgent session API, remote plugin actions, and Shell approval operations over HTTP.

Only available when you install @downcity/server:

pnpm add @downcity/server

Minimal usage

import { AgentHTTP } from "@downcity/server";
import { Agent, Workspace } from "@downcity/agent";

const agent = new Agent({
  id: "demo",
  workspace: new Workspace({ path: process.cwd() }),
  model,
});
const http = new AgentHTTP(agent);

const binding = await http.server().listen({ host: "127.0.0.1", port: 5314 });
// HTTP server listening on http://127.0.0.1:5314

Constructor

new AgentHTTP(agent: Agent)

Methods

listen(options)

Start the HTTP server.

const binding = await http.server().listen({
  host: "127.0.0.1",  // optional: bind address (default: "127.0.0.1")
  port: 5314,            // required: TCP port
});

Returns AgentHttpBinding with the server URL, host, and port. Use router() before startup when you need to mount the transport on your own Hono app.

close()

Stop the HTTP server.

await http.close();

Endpoints

The HTTP server exposes a RESTful interface for session management, execution, and health checks. For the exact route table, see HTTP Endpoints.

When to use it

• You want to access an agent session from a browser or mobile app
• You are building a local dev server with an agent backend
• You need to integrate with HTTP middleware or existing web infrastructure

See also: AgentRPC for the lightweight RPC transport.