Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

📡 Serve

In a nutshell

Run an ACORN bot, local stdio MCP service, or authenticated JSON-RPC or gRPC endpoint with acorn serve.

Start a bot for a GitLab project:

acorn serve bot 12345
acorn serve bot 12345 --event-source webhook \
  --public-url https://bot.example.org --register-webhook

Bot event delivery can use polling, authenticated webhooks, or a hybrid of both. Use acorn serve bot --help to review bind, port, timestamp, polling, and webhook options before exposing the service.

Repository automation is constrained by the workflow section of application configuration passed with --config. The policy is validated before the bot starts; unknown workflow names, formats, actions, effects, and unsafe paths are rejected.

workflow:
  allow-forks: false
  # destination: "12345" # Required, with allow-forks: true, for fork publication.
  workflows:
    repository-quality:
      paths:
        - "**/*.cff"
        - "**/*.{json,jsonc,yaml,yml,md,zonf}"
      formats: [cff, json, jsonc, markdown, yaml, zon]
      actions: [validate, format, link]
      outputs:
        mode: source-and-artifacts
      effects:
        - branch
        - commit
        - commit-status
        - completion-comment
        - draft-merge-request
        - label
        - note
acorn serve bot 12345 --event-source webhook \
  --config /etc/acorn/.acorn.json

Paths are repository-relative globs. Repository content cannot add workflows or widen this policy. Fork writes are denied by default and require both allow-forks: true and an explicit destination; publication then targets only that configured project. Detached bot containers mount this file read-only.

Start the local MCP server with acorn serve mcp. Protocol frames use stdin/stdout and diagnostics use stderr. The default catalog is read-only; global --offline removes open-world tools. --allow-mutation enables persistent tools and requires a local database selected by the global database options:

acorn serve mcp
acorn --offline serve mcp
acorn --database-path ./acorn.db serve mcp --allow-mutation

Start the JSON-RPC 2.0 HTTP endpoint with a dedicated bearer token. The endpoint accepts POST /rpc, requires application/json, limits request bodies, and is read-only unless mutation is explicitly enabled:

export ACORN_SERVICE_TOKEN='replace-with-a-secret'
acorn serve rpc --bind 127.0.0.1:8001

curl --fail-with-body http://127.0.0.1:8001/rpc \
  --header 'Authorization: Bearer replace-with-a-secret' \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"acorn.version"}'

Use global --offline to deny open-world operations. Durable status and replay remain in the catalog; a composition without persistence returns a typed unavailable error.

The Protobuf/gRPC transport exposes the three canonical application operations through the typed, unversioned acorn.service.AcornService. Build the CLI normally and use the same dedicated service token:

cargo build --release --package acorn-cli
export ACORN_SERVICE_TOKEN='replace-with-a-secret'
./target/release/acorn serve grpc --bind 127.0.0.1:50051

Call the typed readability operation with grpcurl and the committed Protobuf contract:

grpcurl -plaintext \
  -H 'authorization: Bearer replace-with-a-secret' \
  -import-path crates/acorn-server/proto \
  -proto acorn/service/service.proto \
  -d '{"text":"A complete sentence for analysis.","metric":"READABILITY_METRIC_ARI"}' \
  127.0.0.1:50051 \
  acorn.service.AcornService/CheckReadability

Loopback development may use plaintext HTTP/2. A non-loopback bind requires a PEM certificate chain and private key:

export ACORN_SERVICE_TOKEN='replace-with-a-secret'
./target/release/acorn serve grpc \
  --bind 0.0.0.0:50051 \
  --tls-cert /etc/acorn/tls/server.pem \
  --tls-key /etc/acorn/tls/server.key

Clients send authorization: Bearer … metadata. Non-loopback clients require TLS; message limits and deadlines apply on both sides. Application errors map to gRPC status codes. The committed contract is at crates/acorn-server/proto/acorn/service/service.proto; generated Rust remains in Cargo’s build output. acorn.version intentionally has no gRPC method. See Protobuf and gRPC.

Next stop: Diagnose the service host with Doctor.