Skip to content
AgentCTX

actx start

actx start

Section titled “actx start”

Start the AgentCTX gateway. This boots the middleware pipeline, connects to backends, and begins accepting CTX operations.

Usage

Section titled “Usage”
Terminal window
actx start [options]

Options

Section titled “Options”
OptionDefaultDescription
--transport <type>"stdio"Transport type: stdio or sse
--protocol <type>—Extension protocol: stdio (newline-delimited JSON)
--port <port>"3100"HTTP port for SSE transport
--http-port <port>"3100"HTTP entry point port
--tcp-port <port>"3101"TCP entry point port
--no-http—Disable the HTTP entry point
--no-tcp—Disable the TCP entry point
--compact—Enable automatic context compaction on every agent turn

Transport Modes

Section titled “Transport Modes”

stdio (default)

Section titled “stdio (default)”

Best for IDE extensions and agent frameworks (VS Code, Cursor, etc.):

Terminal window
actx start
actx start --transport stdio

The gateway reads CTX statements from stdin and writes GatewayResult JSON to stdout. Diagnostic messages go to stderr.

SSE (Server-Sent Events)

Section titled “SSE (Server-Sent Events)”

Best for HTTP clients, web applications, and multi-agent setups:

Terminal window
actx start --transport sse --port 3100

Starts an HTTP SSE server. Agents connect via EventSource and send CTX via POST requests.

Extension Protocol

Section titled “Extension Protocol”

For the VS Code extension, use the structured protocol mode:

Terminal window
actx start --protocol stdio

This sends newline-delimited ServerMessage JSON on stdout and receives ClientMessage JSON on stdin. Different from raw MCP stdio.

Entry Points

Section titled “Entry Points”

In addition to the primary transport, the gateway can expose HTTP and TCP entry points for non-MCP clients:

Terminal window
# All entry points enabled (default)
actx start --transport sse --port 3100 --http-port 3100 --tcp-port 3101


# Disable TCP
actx start --transport sse --no-tcp


# Disable HTTP
actx start --transport sse --no-http

Context Compaction

Section titled “Context Compaction”

The --compact flag enables automatic context compaction using the CTX-ACCE engine:

Terminal window
actx start --compact

This runs the compactor on every agent turn, reducing context window usage by removing stale or redundant entries.

Licensing & Enforcement

Section titled “Licensing & Enforcement”

By default, running actx start locally utilizes the Free Tier WASM Sidecar. This binary is hardcoded via a compilation-boundary limit to strictly enforce a 1-concurrent agent local restriction.

It provides you the full Apache-2.0 core protocol experience but locks multi-tenant orchestration and fleet-wide Convergent Encryption Deduplication behind the enterprise ctx-gateway BSL 1.1 builds.

What Happens on Start

Section titled “What Happens on Start”
  1. Reads .context/actx.yaml configuration
  2. Initializes CryptoManager (loads Ed25519 keypair)
  3. Boots the 15-stage middleware pipeline
  4. Connects to SurrealDB (if SURREAL_URL is set)
  5. Connects to NATS (if NATS_URL is set)
  6. Starts the configured transport listener
  7. Optionally starts HTTP/TCP entry points

Example

Section titled “Example”
Terminal window
$ actx start --transport sse --port 3100
🚀 Starting AgentCTX gateway...
   Transport: sse
   Port: 3100
   HTTP entry point: :3100
   TCP entry point: :3101
✅ Gateway ready

See Also

Section titled “See Also”