How Connectors Work

The CLI Contract

Every AOS connector is a Python CLI tool that implements a standard interface. The contract is defined in the Harness Spec and enforced at runtime.

Global Flags

Every connector must support these flags:

Flag	Purpose
`--json`	Output structured JSON instead of human-readable text
`--mode <tier>`	Set the permission tier for this invocation
`--verbose`	Enable detailed output
`--version`	Print version and exit

Required Commands

Every connector must implement three built-in commands:

Command	Purpose
`capabilities --json`	Self-describe: tool name, version, supported modes, full command list
`health --json`	Report readiness: `healthy`, `needs_setup`, `degraded`, or `error`
`config show --json`	Show current configuration with secrets redacted

JSON Output Envelope

All connector output follows a standard envelope format:

Success

{
  "ok": true,
  "tool": "aos-github",
  "command": "issue.list",
  "data": {
    "issues": [
      { "number": 42, "title": "Fix login bug", "state": "open" }
    ]
  },
  "meta": {
    "mode": "readonly",
    "duration_ms": 234,
    "timestamp": "2026-03-31T12:00:00Z",
    "version": "1.0.0"
  }
}

Error

{
  "ok": false,
  "tool": "aos-github",
  "command": "issue.delete",
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Command requires mode=admin",
    "details": {
      "required_mode": "admin",
      "actual_mode": "readonly"
    }
  },
  "meta": {
    "mode": "readonly",
    "duration_ms": 3,
    "timestamp": "2026-03-31T12:00:01Z",
    "version": "1.0.0"
  }
}

Exit Codes

Code	Meaning
`0`	Success
`2`	Invalid usage / arguments
`3`	Permission denied
`4`	Auth / config error
`5`	Backend unavailable
`6`	Not found
`10`	Internal error

Permission Model

Connectors enforce a four-tier permission model via the --mode flag:

Mode	Access Level	Examples
`readonly`	Read-only queries, no mutations	List issues, search contacts, view invoices
`write`	Create and update operations	Create ticket, send message, update record
`full`	All operations including bulk	Bulk update, batch operations, imports
`admin`	Destructive and configuration	Delete records, revoke access, modify settings

Permission enforcement happens inside the command execution path, not just at the documentation level. Every command is mapped to a minimum mode in permissions.json:

{
  "commands": {
    "issue.list": "readonly",
    "issue.create": "write",
    "issue.delete": "admin",
    "health": "readonly",
    "config.show": "readonly"
  }
}

If you call a write command with --mode readonly, the connector returns a structured error with exit code 3 (permission denied).

Discovery System

ArgentOS discovers connectors automatically from multiple sources:

1. Vendored connectors (`tools/aos/`)

Shipped with the ArgentOS repository. These are the 61 built-in connectors.

2. User connectors (`~/.argentos/connectors/`)

Installed by the user or downloaded from the marketplace.

3. PATH executables

Any binary on your system PATH that starts with aos- is discovered automatically.

4. Custom directories

Set ARGENT_CONNECTOR_REPOS environment variable to a comma-separated list of directories to scan.

Discovery Process

Each discovered connector gets an installState:

State	Meaning
`ready`	Binary found, capabilities parsed, health check passed
`needs-setup`	Binary works but health check reports missing configuration
`repo-only`	Connector directory exists but no runnable binary (needs `pip install`)
`error`	Binary exists but capabilities or health probe failed

The `connector.json` Manifest

Every connector has a connector.json file that describes its metadata, commands, auth requirements, and UI field definitions:

{
  "tool": "aos-github",
  "backend": "github-api",
  "manifest_schema_version": "1.0.0",
  "connector": {
    "label": "GitHub",
    "category": "developer-tools",
    "categories": ["developer-tools", "source-control", "ci-cd"],
    "resources": ["repo", "issue", "pr", "branch"]
  },
  "auth": {
    "kind": "service-key",
    "required": true,
    "service_keys": ["GITHUB_TOKEN"],
    "interactive_setup": [
      "Create a GitHub personal access token with repo scope.",
      "Add GITHUB_TOKEN in API Keys before enabling live reads."
    ]
  },
  "commands": [
    {
      "id": "issue.list",
      "summary": "List issues in a repository",
      "required_mode": "readonly",
      "supports_json": true,
      "resource": "issue",
      "action_class": "read"
    }
  ]
}

Security Baseline

All connectors must follow these security rules:

No shell execution of unsanitized user input
Path-based tools must enforce root allowlist boundaries
config show must redact secrets (API keys, tokens, passwords)
Error messages must not leak credentials
Write operations must respect the permission tier
Destructive operations (delete, revoke) require admin mode

Integration with ArgentOS

When ArgentOS discovers a connector, it:

Registers it in the connector catalog (src/connectors/catalog.ts)
Makes its commands available as agent tools (src/connectors/tools.ts)
Shows it in the dashboard Systems panel with setup status
Allows it to be used in Workflows as action nodes
Makes it available to the execution worker for autonomous task processing

Getting Started

Installation

Channels

Agents

Connectors

Tools

Concepts

Memory

Model Router

The CLI Contract

Global Flags

Required Commands

JSON Output Envelope

Success

Error

Exit Codes

Permission Model

Discovery System

1. Vendored connectors (`tools/aos/`)

2. User connectors (`~/.argentos/connectors/`)

3. PATH executables

4. Custom directories

Discovery Process

The `connector.json` Manifest

Security Baseline

Integration with ArgentOS

​The CLI Contract

​Global Flags

​Required Commands

​JSON Output Envelope

​Success

​Error

​Exit Codes

​Permission Model

​Discovery System

​1. Vendored connectors (tools/aos/)

​2. User connectors (~/.argentos/connectors/)

​3. PATH executables

​4. Custom directories

​Discovery Process

​The connector.json Manifest

​Security Baseline

​Integration with ArgentOS

The CLI Contract

Global Flags

Required Commands

JSON Output Envelope

Success

Error

Exit Codes

Permission Model

Discovery System

1. Vendored connectors (`tools/aos/`)

2. User connectors (`~/.argentos/connectors/`)

3. PATH executables

4. Custom directories

Discovery Process

The `connector.json` Manifest

Security Baseline

Integration with ArgentOS