📡 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.