Docs

amfelt channel

Keep the agent connected so the platform can dispatch runs.
Usage Flags Global flags

Open a persistent connection to the Amfelt platform and keep it open for command delivery and event streaming.

Requires: the agent must already be registered (run amfelt register first). Uses the registered Ed25519 keypair at $AMFELT_DIR/agent-keys/id_ed25519 — ~/.amfelt/agent-keys/id_ed25519 when $AMFELT_DIR is unset — to sign short-lived JWTs for each (re)connect. That identity root is not the workspace root --amfelt-dir sets: --amfelt-dir moves plugins and deployed project files, never the keypair.

Connects to the endpoint register remembered in agent.endpoint beside the identity, unless --api-url, $AMFELT_API_ENDPOINT or api-endpoint in the agent’s config file names another (a different one is used, with a warning naming both). The channel never falls back to the built-in default: the identity is bound to the endpoint it registered with, and the channel sends its signed identity there when it resolves credentials. A dispatched run, and a dispatched SQL render, resolve them at $AMFELT_SECRET_API_URL or secret.api_url instead when either is set; the channel then warns at startup, naming both, when that differs from the remembered endpoint.

A schema import or advise run the platform dispatches must connect to the source and read its schema within the import timeout, 2m by default. Set $AMFELT_IMPORT_TIMEOUT to a Go duration, such as 10m or 1h, to change it: reading the schema of a large CSV or JSON file reads the whole file and can take longer. The channel reads the variable from the environment it started with, so restart it after changing the value. An unset, invalid or non-positive value uses the default.

On any disconnect the client automatically reconnects with exponential backoff (1s → 2s → 4s → max 30s). Stops cleanly on SIGINT / SIGTERM.

Examples:

  # Foreground, against the endpoint the agent registered with
  amfelt channel
  # Against an explicit endpoint
  amfelt channel --api-url "$AMFELT_API_ENDPOINT"
  # Short JWT TTL (rotate more often)
  amfelt channel --token-ttl 2m

Usage  

amfelt channel [flags]

Flags  

FlagTypeDefaultDescription
--api-urlstring—API base URL — overrides $AMFELT_API_ENDPOINT, api-endpoint in the config file and the endpoint remembered at registration
--heartbeat-intervalduration30sInterval between event.agent_heartbeat emissions (shorter = more traffic, faster liveness)
--max-backoffduration30sMaximum reconnect backoff between attempts
--token-ttlduration5m0sJWT lifetime per connect — shorter = tighter replay window, more sign overhead

Global flags  

FlagTypeDefaultDescription
--amfelt-dirstring.amfeltdirectory for workspace files (such as plugins); does not move agent identity (controlled by AMFELT_DIR)
--configstring—directory or filename of the application configuration
-f, --formatstringdefaultlog format to use; either default, pretty, or json
-l, --levelstringinfominimum log level to display; either error, warn, info, or debug
-v, --verboseboolfalsetrigger to use verbose logging

Generated from amfelt v5.6.3.

Last updated on November 1, 2026

On this page