Configuration

Every file and environment variable a Host reads, with its fields. This is the reference; Local and remote Hosts explains how to put them together. Configuration selects what a Host may do and record; it never enters a Program's meaning.

actql.config.jsonCopy Anchor Link

The project file. The CLI searches from the current directory upward for actql.config.json and resolves every path in it relative to the file. The SDKs accept the same fields as connect() options. --config <file> on the CLI selects a different file explicitly, and command flags override its values. It supplies connections, model tasks, the Store and fixtures; it cannot grant permission or name signers — those live in the Host configuration below, which a cloned repository cannot change.

{
  "version": "actql-config/0.1",
  "connectors": "./connectors.json",
  "model_tasks": "./model-tasks.json",
  "lock": "./actql.lock.json",
  "state_dir": "./.actql",
  "profile": "mock",
  "mock": {
    "data": "./mock/data.json",
    "answers": {"model-task:churn-risk.v1": "./mock/churn-risk.v1.answers.yaml"}
  }
}

Host configurationCopy Anchor Link

~/.config/actql/host.json, created by actql init, or the file named with --host-config. It holds what grants and verifies authority: the account configuration, the Host's decisions for delegated operations, and the signers it accepts. A project file cannot add to it.

{
  "version": "actql-host/0.1",
  "account_config": "./accounts.json",
  "run_policy": {
    "principal": "agent:churn-risk",
    "namespace": "acme",
    "policy_contract_cid": "sha256:…",
    "decision": "review",
    "expires_at": "2027-01-01T00:00:00.000Z"
  },
  "effect_policy": {
    "decision": "review",
    "policy_contract_cid": "sha256:…"
  },
  "signers": {
    "ops-approver": {
      "principal": "ops",
      "key_id": "ops-2026",
      "private_key": "./keys/ops.pem",
      "public_key": "./keys/ops.pub.pem",
      "checkpoint_kinds": ["effect_set"]
    }
  }
}

run_policy and effect_policyCopy Anchor Link

When the account configuration answers delegate, the Host consults these policies. Each is its decision for that kind of boundary.

A decision hook in your own code (the decider in Effects and approvals) takes the place of review when the Host is embedded in an application.

signersCopy Anchor Link

Connectors fileCopy Anchor Link

A JSON document listing the connections a Host offers, keyed by the name Programs use (salesforce in salesforce.accounts). Each entry names the Connector, the account or endpoint, and where its credentials come from. Credentials are referenced, never written into the file.

{
  "version": "actql-connectors/0.1",
  "connections": {
    "salesforce": {
      "connector": "salesforce",
      "instance_url": "https://acme.my.salesforce.com",
      "credentials": {"access_token": {"env": "SALESFORCE_ACCESS_TOKEN"}}
    },
    "snowflake": {
      "connector": "snowflake",
      "account": "acme-prod",
      "database": "ANALYTICS",
      "user": "ACTQL",
      "credentials": {"private_key": {"path": "./keys/snowflake.p8"}}
    }
  }
}

The --profile mock option replaces every connection with a mock Connector serving the records in mock.data, and the model with the answers in mock.answers, without editing this file.

Model tasks fileCopy Anchor Link

A JSON document that lists the model tasks INFER may name, each pointing at its definition file, plus the model providers.

{
  "version": "actql-model-tasks/0.1",
  "tasks": {
    "model-task:churn-risk.v1": "./model-tasks/churn-risk.v1.yaml"
  },
  "providers": {
    "openai": {"type": "openai", "api_key_env": "OPENAI_API_KEY"}
  },
  "default_provider": "openai"
}

The definition file format (task, input, instructions, output, model, limits) is described in Models and INFER.

Account configurationCopy Anchor Link

An actql-execution-account-config/0.1 document decides, for every protected operation, whether it is allowed, denied or delegated to the Host's decision. It is the only place authority is granted; a Program cannot change it.

{
  "version": "actql-execution-account-config/0.1",
  "account_id": "acme-prod",
  "entries": [
    {
      "entry_id": "reads",
      "outcome": "allow",
      "principal": {"any_of": ["agent:churn-risk"]},
      "connection": {"all": true},
      "resource": {"all": true},
      "operation": {"any_of": ["read"]},
      "exclusions": []
    },
    {
      "entry_id": "salesforce-writes",
      "outcome": "delegate",
      "principal": {"any_of": ["agent:churn-risk"]},
      "connection": {"any_of": ["salesforce"]},
      "resource": {"all": true},
      "operation": {"any_of": ["effect"]},
      "exclusions": []
    }
  ]
}

Operations are read (any read, including catalog and metadata), infer (a model call), write (data leaving for another system or store) and effect (an Effect commit). Identifiers match by exact equality — no prefixes, patterns or case folding.

Two entries with different outcomes must not overlap; the Host refuses a configuration where they do, regardless of order. Once a configuration exists, an operation that no entry matches is denied, and reported as "no match" rather than as an explicit deny. An invalid file is refused, never read as allow. No file at all means the Host's standard policy (Local and remote Hosts), which needs no configuration to read, infer and hold Effects for approval.

Lock fileCopy Anchor Link

actql lock writes actql.lock.json: the exact Connector contracts, catalog snapshots and model task definitions the Host resolved, each with its identity. actql verify lock checks that they still match. A Run records the lock it ran under, so a changed Connector contract is detected rather than silently used.

Environment variablesCopy Anchor Link

Environment variables select configuration; they are never read by a Program.