# Agent Connections
Source: https://docs.agentsystems.ai/fortress/configuration/agent-connections
Deploy and configure agents
Agents are containerized AI applications that process requests using configured model connections.
## Ways to Add Agents
There are two ways to add agents to your deployment:
1. **Via Index Connections**: Navigate to **[Index Connections](/fortress/configuration/index-connections)** to connect to community agent indexes, then browse and add agents from the **Discover** page
2. **Direct Configuration**: Manually configure agent connections when you know the exact container image details
Before manually configuring agents on this page, you need:
1. [Model connections](/fortress/configuration/model-connections) configured for AI providers
2. [Registry connections](/fortress/configuration/registry-connections) for pulling agent images
## Managing via UI
Navigate to **Configuration → Agent Connections** in the AgentSystems UI at [http://localhost:3001](http://localhost:3001).
The UI allows you to:
* Manually configure agent deployments from known container images
* Edit agent settings and egress controls
* Remove agent connections
## Agent Configuration
Each agent deployment requires:
| Field | Description | Required |
| -------------------------------------- | -------------------------- | --------- |
| `name` | Unique agent identifier | Yes |
| `image` | Full image reference OR | Choice of |
| `registry_connection` + `repo` + `tag` | Registry and image details | one |
| `egress_allowlist` | Allowed outbound URLs | No |
| `artifact_permissions` | File access controls | No |
## Configuration Example
Agent with restricted internet access:
```yaml theme={null}
agents:
- name: web-scraper-agent
image: docker.io/agentsystems/scraper:latest
egress_allowlist:
- "https://api.example.com/*"
- "https://data.provider.com/v1/*"
```
## Manual Configuration
Edit `agentsystems-config.yml` directly:
```yaml theme={null}
config_version: 1
agents:
# Hello world demo agent
- name: hello-world-agent
image: docker.io/agentsystems/hello-world-agent:latest
# Agent from private registry
- name: custom-agent
registry_connection: dockerhub_private
repo: mycompany/custom-agent
tag: v1.0.0
# Agent with egress control
- name: web-agent
image: ghcr.io/company/agent:latest
egress_allowlist:
- "https://api.allowed.com/*"
```
After editing, restart the platform:
```bash theme={null}
agentsystems restart
```
## Agent Lifecycle
When you add an agent to configuration:
* The image is pulled from the specified registry
* A Docker container is created with labels
* Networking and volumes are configured
The gateway discovers agents via Docker labels:
* `agent.enabled=true` marks container as an agent
* `agent.port=8000` specifies the agent's port
Agents may stop after periods of inactivity to save resources.
# Credentials
Source: https://docs.agentsystems.ai/fortress/configuration/credentials
Managing API keys and authentication tokens
Credentials are the foundation of your AgentSystems configuration. They provide access to AI providers and container registries.
Credentials are stored as environment variables. The system design separates credentials from agent containers.
## Managing Credentials via UI
Navigate to **Configuration → Credentials** in the AgentSystems UI at [http://localhost:3001](http://localhost:3001).
The UI allows you to:
* Add new credentials
* Update existing credentials
* Remove unused credentials
Changes made in the UI are written to the `.env` file in your deployment directory.
## Manual Configuration
If editing the `.env` file directly:
1. Open `.env` in your deployment directory
2. Add credentials as key=value pairs
3. Save the file
4. Restart the platform: `agentsystems restart`
## Credential Usage
Credentials are used by:
* **Model Connections**: Reference credentials via environment variable names
* **Registry Connections**: Authenticate to pull agent images
* **Agents**: Credentials are managed by the platform at runtime
# GPU Acceleration
Source: https://docs.agentsystems.ai/fortress/configuration/gpu-acceleration
Enable NVIDIA GPU acceleration for Ollama
## Prerequisites
* Linux with NVIDIA GPU
* [NVIDIA drivers and nvidia-container-toolkit](https://hub.docker.com/r/ollama/ollama) installed
## Configuration
After running `agentsystems init`, edit `compose/local/docker-compose.yml` and add this to the `ollama` service:
```yaml theme={null}
ollama:
image: ollama/ollama:latest
# ... existing configuration ...
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]
```
Then run:
```bash theme={null}
agentsystems up
```
## Verify
Check GPU usage while running a model:
```bash theme={null}
nvidia-smi
```
macOS does not support NVIDIA GPUs in Docker. AMD/Intel GPU support is not currently available.
# Configuration Overview
Source: https://docs.agentsystems.ai/fortress/configuration/index
Configure the AgentSystems platform
AgentSystems offers two ways to add agents: browse community indexes or configure agents directly.
Most agents require AI provider configuration via Model Connections.
## Configuration Paths
**Browse and discover community agents**
Add API keys for AI providers
Navigate to **Configuration → Credentials**
Connect to AI providers using your credentials
Navigate to **Configuration → Model Connections**
Connect to community agent indexes
Navigate to **Configuration → Index Connections**
Discover and add agents from indexes
Navigate to **Discover** to browse available agents
**Manually configure agents from known images**
Add API keys for AI providers and container registries
Navigate to **Configuration → Credentials**
Connect to AI providers using your credentials
Navigate to **Configuration → Model Connections**
Set up container registries to pull agent images
Navigate to **Configuration → Registry Connections**
Configure agent deployments from container images
Navigate to **Configuration → Agent Connections**
## Configuration Methods
Use the AgentSystems UI at [http://localhost:3001](http://localhost:3001)
The UI includes:
* Visual configuration forms
* Form validation
* Direct file management
Edit configuration files directly:
**`.env`** - API keys and credentials
```bash theme={null}
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
```
**`agentsystems-config.yml`** - Platform configuration
```yaml theme={null}
config_version: 1
model_connections:
# Model configs
registry_connections:
# Registry configs
agents:
# Agent deployments
```
## Quick Links
### Connections
Connect to AI providers
Browse community agents
Add container registries
Configure agent deployments
### System
Manage API keys
## Configuration Files Location
Configuration files are stored in your deployment directory:
```
my-deployment/
├── .env # API keys and credentials
├── agentsystems-config.yml # Platform configuration
└── docker-compose.yml # Service definitions
```
After making configuration changes, restart the platform with `agentsystems restart` for changes to take effect.
# Index Connections
Source: https://docs.agentsystems.ai/fortress/configuration/index-connections
Discover community agents from public indexes
Index connections allow AgentSystems to discover and browse community agents from public agent indexes. Connect to multiple indexes to expand your agent library.
AgentSystems does not review or endorse software in any index.
## Managing via UI
Navigate to **Configuration → Index Connections** in the AgentSystems UI at [http://localhost:3001](http://localhost:3001).
The UI allows you to:
* Add public agent indexes
* Enable/disable index connections
* Browse agents from enabled indexes on the Discover page
## Configuration Structure
Each index connection requires:
| Field | Description | Required |
| ------------- | ------------------------------------------------------------ | -------- |
| `name` | Unique identifier (lowercase, numbers, hyphens, underscores) | Yes |
| `url` | Index API URL (must be http\:// or https\://) | Yes |
| `enabled` | Whether this index is active | Yes |
| `description` | Human-readable description | No |
## Manual Configuration
Edit `agentsystems-config.yml` directly:
```yaml theme={null}
config_version: 1
index_connections:
# AgentSystems community index
agentsystems-community:
url: https://agentsystems.github.io/agent-index
enabled: true
description: AgentSystems community index
# Custom company index
mycompany-index:
url: https://index.mycompany.com
enabled: true
description: Internal agent catalog
```
After editing, restart the platform:
```bash theme={null}
agentsystems restart
```
## Index Structure
Agent indexes may provide:
* Agent metadata (name, description, developer)
* Container image location and tag
* Model requirements
* Egress allowlist
* Additional metadata
## Enabling an Index
When enabling an index, you acknowledge that this third-party software has not been reviewed or endorsed by AgentSystems.
Provide the index URL and a unique name for the connection.
Check the "Enabled" checkbox and acknowledge the community software disclaimer.
Navigate to **Discover** to browse and add agents from enabled indexes.
## Disabling an Index
Disabling an index connection will:
* Hide agents from that index on the Discover page
* Not affect already-deployed agents from that index
* Allow you to re-enable the connection at any time
## Index Security
AgentSystems does not review or endorse software in any index.
If you change an index URL while it's enabled, you must re-acknowledge that this third-party software has not been reviewed or endorsed by AgentSystems.
# Model Connections
Source: https://docs.agentsystems.ai/fortress/configuration/model-connections
Connect to AI providers
Model connections define how agents access AI providers. Each connection maps a model ID to a specific provider and authentication method.
Set up [credentials](/fortress/configuration/credentials) before configuring model connections.
## Managing via UI
Navigate to **Configuration → Model Connections** in the AgentSystems UI at [http://localhost:3001](http://localhost:3001).
The UI allows you to:
* Add connections to AI providers
* Enable/disable connections
## Supported Models
| Model ID | Display Name | Providers | Required Credentials |
| ------------------- | ----------------- | ---------------------- | -------------------------------------- |
| `gpt-4o` | GPT-4o | OpenAI | `OPENAI_API_KEY` |
| `gpt-4o-mini` | GPT-4o mini | OpenAI | `OPENAI_API_KEY` |
| `claude-3-5-sonnet` | Claude 3.5 Sonnet | Anthropic, AWS Bedrock | `ANTHROPIC_API_KEY` or AWS credentials |
| `claude-3-5-haiku` | Claude 3.5 Haiku | Anthropic, AWS Bedrock | `ANTHROPIC_API_KEY` or AWS credentials |
| `llama3.1:8b` | Llama 3.1 8B | Ollama, AWS Bedrock | None (Ollama) or AWS credentials |
| `gemma3:1b` | Gemma 3 1B | Ollama | None (local) |
| `nova-pro` | Amazon Nova Pro | AWS Bedrock | AWS credentials |
For the full list of supported models, check the Model Connections page in the UI at [http://localhost:3001](http://localhost:3001).
## Configuration Structure
Each model connection requires:
| Field | Description | Required |
| --------------------------- | ----------------------------------------------------------------- | -------- |
| `hosting_provider` | Provider name (`openai`, `anthropic`, `amazon_bedrock`, `ollama`) | Yes |
| `hosting_provider_model_id` | Provider-specific model identifier | Yes |
| `enabled` | Whether this connection is active | Yes |
| `auth` | Authentication configuration | Yes |
| `hosting_provider_base_url` | Custom endpoint (Ollama only) | No |
| `hosting_provider_region` | AWS region (Bedrock only) | No |
## Manual Configuration
Edit `agentsystems-config.yml` directly:
```yaml theme={null}
config_version: 1
model_connections:
# Give each connection a unique ID
my-gpt4-connection:
hosting_provider: openai
hosting_provider_model_id: gpt-4
enabled: true
auth:
method: api_key
api_key_env: OPENAI_API_KEY
my-claude-connection:
hosting_provider: anthropic
hosting_provider_model_id: claude-3-opus-20240229
enabled: true
auth:
method: api_key
api_key_env: ANTHROPIC_API_KEY
```
After editing, restart the platform:
```bash theme={null}
agentsystems restart
```
# Registry Connections
Source: https://docs.agentsystems.ai/fortress/configuration/registry-connections
Configure container registry access
Registry connections allow AgentSystems to pull agent images from container registries. You can connect to multiple registries simultaneously.
Public registries typically work without credentials; some images may require authentication or be rate-limited. Private registries require authentication configured in [credentials](/fortress/configuration/credentials).
## Managing via UI
Navigate to **Configuration → Registry Connections** in the AgentSystems UI at [http://localhost:3001](http://localhost:3001).
The UI allows you to:
* Add public and private registries
* Configure authentication methods
* Enable/disable registry connections
## Configuration Structure
Each registry connection requires:
| Field | Description | Required |
| ------------------- | ------------------------------------------------ | -------- |
| `url` | Registry hostname (e.g., `docker.io`, `ghcr.io`) | Yes |
| `enabled` | Whether this connection is active | Yes |
| `auth.method` | Authentication type: `none`, `basic`, `bearer` | Yes |
| `auth.username_env` | Environment variable for username (basic auth) | No |
| `auth.password_env` | Environment variable for password (basic auth) | No |
| `auth.token_env` | Environment variable for token (bearer auth) | No |
## Manual Configuration
Edit `agentsystems-config.yml` directly:
```yaml theme={null}
config_version: 1
registry_connections:
# Public Docker Hub (no auth needed)
dockerhub_public:
url: docker.io
enabled: true
auth:
method: none
# Private Docker Hub
dockerhub_private:
url: docker.io
enabled: true
auth:
method: basic
username_env: DOCKERHUB_USER
password_env: DOCKERHUB_TOKEN
# GitHub Container Registry
github:
url: ghcr.io
enabled: true
auth:
method: basic
username_env: GHCR_USER
password_env: GHCR_TOKEN
```
After editing, restart the platform:
```bash theme={null}
agentsystems restart
```
## Registry Usage in Agent Configuration
Agents reference registry connections when specifying their image source:
```yaml theme={null}
agents:
- name: my-agent
registry_connection: dockerhub_private # References the connection ID
repo: mycompany/my-agent
tag: v1.0.0
```
## Authentication Methods
For public registries and images. No credentials required.
Username and password/token authentication. Used by Docker Hub, GHCR, and many private registries.
Token-based authentication. Common for enterprise registries.
# List on Index
Source: https://docs.agentsystems.ai/fortress/deploy-agents/list-on-index
Add your agent to the public index for discovery
Publishing metadata to the agent index makes your agent **discoverable** in the AgentSystems platform. The index contains metadata only - your actual agent image can be public or private. Metadata submissions are automatically validated and merged.
## Prerequisites
* GitHub account with commit signing enabled ([Setup Guide](https://docs.github.com/en/authentication/managing-commit-signature-verification))
* Agent deployed (see [Quickstart](/fortress/deploy-agents/quickstart))
* 5 minutes
**Commit Signing Required**: All commits in your PR must be signed with a verified GPG or SSH key. Unverified commits will be rejected by the auto-merge workflow. This requirement helps verify that commits are cryptographically signed and match the author identity.
## Overview
The [agent-index repository](https://github.com/agentsystems/agent-index) is an open-source, Git-based registry for agent metadata enabling federated discovery. Instead of a centralized API:
* Developers manage their own YAML files in `developers/your-github-username/`
* Pull requests are automatically validated and merged—no manual approval needed
* Metadata is published to `https://agentsystems.github.io/agent-index/`
* The AgentSystems UI consumes this index (and can connect to multiple indexes)
* Anyone can fork the repository and run their own independent index
**Disclaimer**: Inclusion in the index does not constitute endorsement. The index provides metadata submitted by developers and does not verify agent quality, functionality, or security.
## Step 1: Fork the Repository
Go to [github.com/agentsystems/agent-index](https://github.com/agentsystems/agent-index) and click **"Fork"**.
Clone your fork:
```bash theme={null}
git clone https://github.com/your-github-username/agent-index.git
cd agent-index
```
## Step 2: Create Your Developer Profile
Create your developer folder (must match your GitHub username):
```bash theme={null}
mkdir -p developers/your-github-username
```
Copy the example profile:
```bash theme={null}
cp examples/profile.yaml developers/your-github-username/profile.yaml
```
Edit `developers/your-github-username/profile.yaml`:
```yaml theme={null}
name: Your Name or Company
developer: your-github-username # Must match folder name
type: individual # individual, organization, company, or enterprise
bio: Developer of AI agents for...
website: https://example.com
support_email: hello@example.com
# Optional fields
tagline: Building the future of AI agents
location: San Francisco, CA
twitter_handle: yourhandle
linkedin_url: https://linkedin.com/in/yourprofile
expertise:
- Natural Language Processing
- Data Analysis
- Multi-Agent Systems
open_to_collaboration: true
```
**Required**:
* `name` (string): Display name
* `developer` (string): Developer namespace - must match folder name
**Optional**:
* `type` (string): "individual", "organization", "company", or "enterprise"
* `avatar_url` (string): Profile image URL
* `bio` (string): Short biography
* `tagline` (string): Short tagline or slogan
* `company` (string): Company name
* `location` (string): Geographic location
* `years_experience` (integer): Years in AI/ML
* `website` (string): Your website URL
* `support_email` (string): Support email
* `documentation_url` (string): Docs URL
* `twitter_handle` (string): Twitter/X handle (without @)
* `linkedin_url` (string): LinkedIn profile
* `discord_username` (string): Discord username
* `expertise` (array): Areas of expertise
* `featured_work` (array): URLs to featured projects
* `open_to_collaboration` (boolean): Open to collaboration
* `sponsor_url` (string): GitHub Sponsors or similar
## Step 3: Add Your Agent Metadata
Create the agents folder:
```bash theme={null}
mkdir -p developers/your-github-username/agents
```
Copy the example agent:
```bash theme={null}
# Create your agent directory
mkdir -p developers/your-github-username/agents/your-agent
# Copy example files
cp examples/agents/demo-agent/agent.yaml developers/your-github-username/agents/your-agent/
cp examples/agents/demo-agent/versions.yaml developers/your-github-username/agents/your-agent/
cp examples/agents/demo-agent/0.1.0.yaml developers/your-github-username/agents/your-agent/
```
The directory structure will be:
```
developers/your-github-username/agents/your-agent/
agent.yaml # Agent identity (who/what it is)
versions.yaml # Version management (which versions)
0.1.0.yaml # Version specification (how it behaves)
```
Edit the three YAML files:
**`agent.yaml`** - Set your agent identity:
* `developer` - Must match your GitHub username
* `name` - Must match directory name
* `description`, `container_image`, `tags`, `capabilities` - See examples folder for all fields
**`versions.yaml`** - Set version management:
* `latest_version: "0.1.0"`
* `listed_versions:` with `- "0.1.0"` (use dash notation)
**`0.1.0.yaml`** - Set version-specific attributes:
* `version` - Must match filename ("0.1.0")
* `model_dependencies:` with `- gemma3:1b` (use dash notation)
* `readiness_level`, `input_schema`, `facets` - See examples folder for all fields
See `examples/agents/demo-agent/` in the repository for complete examples of all three files with all available fields and documentation.
**Required in agent.yaml (Agent Identity)**:
* `name` (string): Agent name (lowercase, alphanumeric, hyphens)
* `developer` (string): Your GitHub username (must match folder name)
* `description` (string): Short description
* `container_image` (string): Container image reference without tag (e.g., docker.io/user/agent)
**Optional in agent.yaml (Agent Identity)**:
* `source_repository_url` (string): Source code URL
* `primary_function` (string): Primary function category
* `tags` (array): Searchable tags
* `capabilities` (array): High-level capability descriptions
**Required in versions.yaml (Version Management)**:
* `latest_version` (string): Latest version (must match an existing .yaml file)
* `listed_versions` (array): Versions visible in discovery (each must match an existing .yaml file)
**Required in .yaml files (Version Specification)**:
* `version` (string): Semantic version (e.g., "0.1.0" or "1.0.0-beta.1"), used as container image tag
* `model_dependencies` (array): Required AI models (at least one)
**Optional in .yaml files**:
* `readiness_level` (string): "experimental", "beta", "production", or "deprecated"
* `container_image_access` (string): "public" or "private"
* `source_repository_access` (string): "public" or "private"
* `required_egress` (array): Required network egress URLs
* `required_integrations` (array): Required external integrations
* `input_types` (array): Supported input data types
* `output_types` (array): Supported output data types
* `input_schema` (object): Input parameter schema
* `facets` (object): Behavioral characteristics and categorization
* `context` (string): Operating context (personal, professional, general)
* `autonomy` (string): Autonomy level (Assist, Co-pilot, Auto-pilot)
* `latency` (string): Latency profile (real-time, interactive, batch)
* `cost_profile` (string): Cost model (free, $/task, $/month)
* `modalities` (array): Supported modalities (text, image, audio, video)
* `domains` (array): Application domains
* `model_tooling` (array): Model frameworks (LLM, RAG, fine-tuned, embeddings)
* `industries` (array): Target industries
* `integrations` (array): Supported integrations
* `release_notes` (string): Markdown-formatted release notes
See the schemas for complete details:
* [agent-identity.schema.json](https://github.com/agentsystems/agent-index/blob/main/schema/agent-identity.schema.json) - agent.yaml
* [versions.schema.json](https://github.com/agentsystems/agent-index/blob/main/schema/versions.schema.json) - versions.yaml
* [agent-version.schema.json](https://github.com/agentsystems/agent-index/blob/main/schema/agent-version.schema.json) - .yaml
## Step 4: Validate Locally (Optional)
Validation runs automatically on your PR, but testing locally helps catch issues early.
```bash theme={null}
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install pyyaml jsonschema
python scripts/validate.py all
```
Should output:
```
✅ All validations passed!
```
## Step 5: Submit Pull Request
Commit and push:
```bash theme={null}
git add developers/your-github-username/
git commit -m "Add your-github-username profile and your-agent"
git push origin main
```
Go to your fork on GitHub and click **"Contribute"** → **"Open pull request"**.
## What Happens Next
Your PR triggers automated workflows:
1. **Policy Gate**: Validates folder ownership (checks your GitHub username matches folder name)
2. **YAML Validation**: Checks syntax and schema compliance
3. **Auto-Merge**: If all checks pass, PR is automatically approved and merged
4. **Build & Deploy**: Index is rebuilt and published to GitHub Pages
Your agent should appear at `https://agentsystems.github.io/agent-index/` shortly after the build completes.
## Publishing New Versions
To publish a new version of your agent:
1. Create a new version file in your agent directory:
```bash theme={null}
# Copy your current version as a template
cp developers/your-github-username/agents/your-agent/0.1.0.yaml \
developers/your-github-username/agents/your-agent/0.2.0.yaml
```
2. Edit the new version file:
* Update `version: "0.2.0"` (must match filename)
* Modify any behavioral changes (model, facets, schema, etc.)
* Add release notes
3. Update versions.yaml:
* Change `latest_version: "0.1.0"` to `latest_version: "0.2.0"`
* Add `"0.2.0"` to `listed_versions` array
* Optionally remove old versions from `listed_versions` to hide them
```yaml theme={null}
latest_version: "0.2.0"
listed_versions:
- "0.1.0" # Keep if users might want old version
- "0.2.0" # New version
```
4. Commit and push:
```bash theme={null}
git add developers/your-github-username/agents/your-agent/
git commit -m "Release 0.2.0 of your-agent"
git push origin main
```
**Git diff clarity**: Adding 0.2.0 shows as a clean new file in your PR, making reviews simple and clear.
## Updating Agent Identity
To update your agent's identity (description, tags, capabilities):
1. Edit `developers/your-github-username/agents/your-agent/agent.yaml`
2. Commit and push to your fork
3. Open a new pull request
4. Auto-merge handles the rest
Note: Identity fields affect all versions. Version-specific changes go in the .yaml files.
## Security Model
The index uses **fork-based ownership**:
* ✅ Only you can modify `developers/your-github-username/` (checked via fork ownership)
* ✅ PRs touching only your folder auto-merge
* ✅ PRs touching core files require maintainer approval
* ✅ Multiple validation layers protect the index
## Troubleshooting
### PR not auto-merging
**Check**:
1. All files are in `developers/your-github-username/` (folder name must match your GitHub username exactly)
2. YAML validation passes (check the workflow logs)
3. You're submitting from a fork (not a branch in the main repo)
4. All commits are signed and verified (see below)
### YAML validation fails
Common issues:
* **Syntax error**: Check YAML indentation (use spaces, not tabs)
* **Missing required field**: Ensure `name`, `developer` (in profile.yaml), `version`, `description`, and `model_dependencies` are present
* **Invalid value**: Check enum fields like `readiness_level`
Run `python scripts/validate.py all` locally to see detailed error messages.
### Folder ownership check fails
**Error**: "Developer folder (your-name) does not match PR head repository owner (different-name)"
**Solution**: Your folder name must exactly match your GitHub username. If your fork is under a different account, the folder name must match that account.
### Unverified commits
**Error**: "PR contains unverified commits. All commits must be signed with a verified GPG or SSH key."
**Solution**:
1. Verify your git config matches your signing key:
```bash theme={null}
git config user.name # Should match your GitHub username
git config user.email # Should match your signing key email
```
2. Set up commit signing: [GitHub Docs](https://docs.github.com/en/authentication/managing-commit-signature-verification)
3. Configure auto-signing:
```bash theme={null}
git config commit.gpgsign true # For GPG
# or
git config gpg.format ssh # For SSH keys
git config user.signingkey ~/.ssh/id_ed25519.pub
```
4. If commits are already pushed, you'll need to amend and force-push (or create a new PR with signed commits)
## Next Steps
* **Discover agents**: Browse the index at [agentsystems.github.io/agent-index](https://agentsystems.github.io/agent-index/)
* **Deploy private agents**: See [Deploying Private Agents](/fortress/deploy-agents/private-agents)
* **Review schemas**: Full schemas at [github.com/agentsystems/agent-index/tree/main/schema](https://github.com/agentsystems/agent-index/tree/main/schema)
# Deploying Private Agents
Source: https://docs.agentsystems.ai/fortress/deploy-agents/private-agents
Deploy agents using private Docker registries
Private agents use private repositories to control access to your agent images. You can use private Docker Hub repositories, GitHub Container Registry (GHCR), or Harbor.
## Docker Hub Private Repository
This guide shows how to deploy an agent using a private Docker Hub repository with access tokens.
### Prerequisites
* AgentSystems platform running ([Installation Guide](/fortress/getting-started/quickstart))
* Docker installed and running
* Docker Hub account (free at [hub.docker.com](https://hub.docker.com))
### Step 1: Get the Template
Go to [github.com/agentsystems/agent-template](https://github.com/agentsystems/agent-template) and click **"Use this template"** → **"Create a new repository"**.
Name it `demo-agent-private` and clone it:
```bash theme={null}
git clone https://github.com/your-org/demo-agent-private.git
cd demo-agent-private
```
### Step 2: Review the Template
The template includes a demo agent. This guide deploys it as a private agent (not publicly discoverable).
To customize the agent logic, edit `main.py` and modify the agent's behavior. For this guide, we'll deploy the template as-is.
### Step 3: Build and Push to Private Repository
Log in to Docker Hub:
```bash theme={null}
docker login
```
Build and push (replace `your-org`):
```bash theme={null}
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t your-org/demo-agent-private:0.1.0 \
-t your-org/demo-agent-private:latest \
--push \
.
```
This takes 5-10 minutes.
### Step 4: Keep Repository Private
Docker Hub creates new repositories as **public by default**. Make sure to change it to private.
1. Go to [hub.docker.com](https://hub.docker.com)
2. Open your repository: `your-org/demo-agent-private`
3. Click **Settings** → **Visibility settings** → Change to **Private** → **Save**
### Step 5: Generate Access Token
Generate a read-only access token for the platform to pull your private image.
Use **read-only tokens with expiration dates** for security. The platform only needs read access to pull images.
**For Personal Repositories:**
1. Go to Settings
2. Click **Personal access tokens**
3. Click **Generate new token**
4. Access token description: `AgentSystems Read Access`
5. Set an expiration date (recommended for demos)
6. Access permissions: **Read-only**
7. Click **Generate**
8. **Copy the token** (you won't see it again)
**For Organization Repositories:**
1. Go to your organization settings
2. Navigate to **Access tokens**
3. Click **Generate access token**
4. Label: `AgentSystems Image Pull Access`
5. Set an expiration date (recommended for demos)
6. Give the token the Image Pull scope for the necessary repository
7. Click **Generate token**
8. **Copy the token** (you won't see it again)
### Step 6: Add Credentials to Platform
Open [localhost:3001/configuration/credentials](http://localhost:3001/configuration/credentials)
Add your Docker Hub username:
* Click **"Add Credential"**
* **Name**: `PRIVATE_DOCKERHUB_USERNAME`
* **Value**: Your Docker Hub username or organization
* Click **Add Variable**
Add your access token:
* Click **"Add Credential"** again
* **Name**: `PRIVATE_DOCKERHUB_TOKEN`
* **Value**: Paste the token from Step 5
* Click **Add Variable**
### Step 7: Create Registry Connection
Open [localhost:3001/configuration/registries](http://localhost:3001/configuration/registries) and click **"Add Registry"**:
* **Name**: `dockerhub_yourorg_private` (replace `yourorg` with your username/org)
* **URL**: `docker.io`
* **Authentication Method**: `Basic (Username/Password)`
* **Username Environment Variable**: `PRIVATE_DOCKERHUB_USERNAME`
* **Password Environment Variable**: `PRIVATE_DOCKERHUB_TOKEN`
* **Enabled**: ✓ (checked)
Click **Add Registry**.
### Step 8: Add Agent to Platform
Open [localhost:3001/configuration/agents](http://localhost:3001/configuration/agents) and click **"Add Agent"**:
* **Name**: `demo-agent-private`
* **Repository**: `your-org/demo-agent-private`
* **Registry**: `dockerhub_yourorg_private`
* **Tag**: `latest`
* **Egress Allowlist**: Leave blank (no external API calls needed)
Click **"Add Agent"**.
### Step 9: Restart and Test
Navigate to your AgentSystems deployment directory and restart:
```bash theme={null}
cd /path/to/agentsystems
agentsystems restart
```
Test it:
1. Go to [localhost:3001/agents](http://localhost:3001/agents)
2. Click on `demo-agent-private`
3. Click **"Turn On"**
4. Click **"Execute"**
You should see historical events and a story!
### What You Built
Your private agent is deployed:
* Uses a **private Docker Hub repository**
* Requires credentials to pull and deploy
* Runs in a Docker container
* Accessible at `http://localhost:18080/invoke/demo-agent-private`
## GitHub Container Registry (GHCR)
Coming soon: A guide to deploying private agents using GitHub Container Registry (ghcr.io).
## Harbor
Coming soon: A guide to deploying private agents using Harbor registry.
# Quickstart
Source: https://docs.agentsystems.ai/fortress/deploy-agents/quickstart
Deploy your first agent to AgentSystems in under 10 minutes
AgentSystems is an **open agent platform** where agents can be **public or private**. This quickstart deploys a public agent - your agent will be available on Docker Hub for others to pull and run. You can also deploy private agents for your organization - see the next steps after completing this guide.
## Prerequisites
* AgentSystems platform running ([Installation Guide](/fortress/getting-started/quickstart))
* Docker installed and running
* Docker Hub account (free at [hub.docker.com](https://hub.docker.com))
## Step 1: Get the Template
Go to [github.com/agentsystems/agent-template](https://github.com/agentsystems/agent-template) and click **"Use this template"** → **"Create a new repository"**.
Name it `demo-agent` and clone it:
```bash theme={null}
git clone https://github.com/your-org/demo-agent.git
cd demo-agent
```
## Step 2: Review the Template
The template includes a demo agent that:
* Accepts a date (e.g., "April 1")
* Returns historical events for that date
* Creates a story from those events
* Uses `gemma3:1b` model
This quickstart deploys the template as-is without modification.
## Step 3: Build and Push
Docker Hub creates new repositories as **public by default**. Your agent image will be publicly accessible immediately after pushing, allowing anyone to pull and run your agent.
Log in to Docker Hub:
```bash theme={null}
docker login
```
Build and push (replace `your-org`):
```bash theme={null}
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t your-org/demo-agent:0.1.0 \
-t your-org/demo-agent:latest \
--push \
.
```
This takes 5-10 minutes.
## Step 4: Verify Repository Visibility
Confirm your repository is public:
1. Go to [hub.docker.com](https://hub.docker.com)
2. Open your repository: `your-org/demo-agent`
3. Check **Settings** → **Visibility settings** shows **Public**
If it shows Private, change it to Public and save.
## Step 5: Add Agent to Platform
Open [localhost:3001/configuration/agents](http://localhost:3001/configuration/agents):
* **Name**: `demo-agent`
* **Repository**: `your-org/demo-agent`
* **Registry**: `dockerhub_public`
* **Tag**: `latest`
* **Egress Allowlist**: Leave blank (no external API calls needed)
Click **"Add Agent"**.
## Step 6: Restart and Test
Navigate to your AgentSystems deployment directory and restart:
```bash theme={null}
cd /path/to/agentsystems
agentsystems restart
```
Test it:
1. Go to [localhost:3001/agents](http://localhost:3001/agents)
2. Click on `demo-agent`
3. Click **"Turn On"**
4. Click **"Execute"**
You should see historical events and a story!
## What You Built
Your agent is now deployed on the **open AgentSystems platform**.
Your agent:
* Uses `gemma3:1b` (local model, no API keys needed)
* Accepts a date and returns historical events
* Runs in a Docker container
* Is accessible at `http://localhost:18080/invoke/demo-agent`
* Is publicly available on Docker Hub for others to use
## Next Steps
**Deploy a Private Agent**: This quickstart deployed a public agent. To keep your agent private for your organization, see [Deploying Private Agents](/fortress/deploy-agents/private-agents).
# Supported Frameworks
Source: https://docs.agentsystems.ai/fortress/deploy-agents/supported-frameworks
List of agent frameworks supported by AgentSystems
# Supported Frameworks
Use these frameworks to build agents with `get_model()`:
```python theme={null}
from agentsystems_toolkit import get_model
model = get_model("claude-sonnet-4", "langchain", temperature=0)
```
## Currently Supported
* **LangChain** - Use with LangChain chains and LangGraph
## Planned Support
* OpenAI SDK
* Anthropic SDK
* LlamaIndex
* CrewAI
* Google ADK
***
**Note:** The framework parameter determines which type of model object is returned.
# Supported Models
Source: https://docs.agentsystems.ai/fortress/deploy-agents/supported-models
List of model IDs supported by AgentSystems
# Supported Models
Use these model IDs in your agent code with `get_model()`:
```python theme={null}
from agentsystems_toolkit import get_model
model = get_model("claude-sonnet-4", "langchain", temperature=0)
```
## Claude (Anthropic)
* `claude-opus-4.1`
* `claude-opus-4`
* `claude-sonnet-4`
* `claude-sonnet-3.7`
* `claude-3-5-sonnet`
* `claude-3-5-haiku`
* `claude-haiku-3`
## GPT (OpenAI)
* `gpt-5`
* `gpt-5-mini`
* `gpt-5-nano`
* `gpt-4.1`
* `gpt-4o`
* `gpt-4o-mini`
* `gpt-4-turbo`
* `o1`
* `o1-mini`
## Amazon Nova
* `nova-premier`
* `nova-pro`
* `nova-lite`
* `nova-micro`
## Llama (Meta)
* `llama3.3:70b`
* `llama3.1:8b`
* `llama3.2:3b`
* `llama3.2:1b`
## Gemma (Google)
* `gemma3:4b`
* `gemma3:1b`
* `gemma2:2b`
***
## Configuration Required
**Before using any model in your agent**, the platform operator must configure the model connection in the AgentSystems UI:
1. Navigate to **Configuration → Model Connections**
2. Add the model ID (e.g., `claude-sonnet-4`)
3. Select hosting provider (Anthropic, OpenAI, Bedrock, Ollama)
4. Configure authentication (API keys, AWS credentials, etc.)
5. Enable the connection
Agent builders reference the model ID in code, but the actual hosting provider and credentials are configured by whoever runs the AgentSystems platform.
# Introduction
Source: https://docs.agentsystems.ai/fortress/getting-started/index
Self-hosted platform for discovering and running AI agents
## Self-hosted platform for discovering and running AI agents
Deploy specialized agents on your infrastructure—without building from scratch or using SaaS.
**What is AgentSystems?** A self-hosted platform that combines a federated agent ecosystem, provider portability, and container isolation. Browse community agents, deploy on your infrastructure, and switch between AI providers through configuration.
## Why AgentSystems?
Teams want to use specialized AI agents but face a dilemma:
* 🔒 **SaaS agents** require sending data to third parties
* 🛠️ **Building from scratch** takes weeks of development per agent (most teams lack ML expertise)
* 🐳 **Manual Docker orchestration** means configuring networks, volumes, proxies, and API keys for each agent
**AgentSystems provides** a standardized runtime and ecosystem:
* **Federated Agent Ecosystem**: Git-based agent index where developers publish via GitHub forks
* **Provider Portability**: Switch from OpenAI to Anthropic to Ollama through configuration
* **Container Isolation**: Each agent runs in its own Docker container with configurable egress filtering
* **Audit Trail**: Hash-chained logs for operation tracking
## Key Capabilities
Browse and add agents from community indexes
Deploy AI agents on your hardware with Docker
Use OpenAI, Anthropic, AWS Bedrock, or local models
Operation logging to PostgreSQL database
## Use Cases
The platform targets scenarios requiring local AI execution:
* Processing documents on your infrastructure
* Running AI workloads on-premise
* Keeping data within your own environment
* Testing multiple AI providers
* Building containerized AI agents
# Key Concepts
Source: https://docs.agentsystems.ai/fortress/getting-started/key-concepts
How AgentSystems components work together
AgentSystems consists of several interconnected components that work together as an agent platform.
## Core Components
**Agent Control Plane (Gateway)**
The gateway is the central orchestration layer that:
* Discovers agent containers via Docker labels
* Routes requests to agents
* Handles container lifecycle operations
* Routes requests via HTTP proxy
* Logs operations to database
Runs on port 18080 (external) / 8080 (internal)
**AgentSystems UI**
Web interface for platform management:
* Agent discovery and execution
* Configuration management
* Execution monitoring and history
* Audit log viewing
Accessible at [http://localhost:3001](http://localhost:3001)
**AgentSystems SDK**
Command-line tool for platform operations:
* Deployment initialization (`agentsystems init`)
* Service management (`agentsystems up/down`)
* Agent execution (`agentsystems run`)
* Log viewing (`agentsystems logs`)
**PostgreSQL**
Persistent storage for:
* Execution history
* Audit logs with hash-chaining
* Agent metadata
* Configuration data
## Request Flow
User initiates agent execution via UI or SDK CLI
Control plane receives request, generates thread ID, and logs to database
Gateway locates target agent container via Docker labels (`agent.enabled=true`)
Gateway attempts to start the container if needed
Gateway forwards request to agent's `/invoke` endpoint with `X-Thread-Id` header
Agent processes request using configured AI models and saves outputs to `/artifacts/{thread_id}/out/`
Agent returns response, gateway logs completion, and results are returned
## Network Architecture
Components communicate through Docker networks.
### Docker Networks
* **agents-net**: Platform services communication
* **agents-int**: Agent-to-gateway isolated network
### Port Mappings
| Service | External Port | Internal Port |
| ---------- | ------------- | ------------- |
| UI | 3001 | 3001 |
| Gateway | 18080 | 8080 |
| PostgreSQL | - | 5432 |
| Proxy | - | 3128 |
## File System Structure
### Artifacts Directory
Each agent invocation gets isolated storage:
```
/artifacts/
├── {thread-id}/
│ ├── in/ # Input files from client
│ └── out/ # Output files from agent
```
### Configuration Files
The UI manages configuration files that control the platform:
* **`.env`**: API keys and credentials
* **`agentsystems-config.yml`**: Model connections, registries, and agents
Configuration changes made in the UI are written to these files and take effect on platform restart.
## System Architecture
Each agent runs in a separate Docker container.
API keys are stored in environment variables separate from agent containers.
Operations are logged to PostgreSQL with request/response tracking.
HTTP proxy configuration supports URL allowlist functionality.
# Manual Installation
Source: https://docs.agentsystems.ai/fortress/getting-started/manual-installation
Step-by-step guide to manually install AgentSystems
## Prerequisites
### 1. Python 3.11 or Higher
AgentSystems requires Python 3.11+. Check your version:
```bash theme={null}
python3 --version
```
If you need to upgrade, see the [Python downloads page](https://www.python.org/downloads/).
### 2. Docker
Docker is required to run AgentSystems containers.
* **macOS**: Install [Docker Desktop](https://www.docker.com/products/docker-desktop/)
* **Linux**: Follow the [official Docker Engine installation guide](https://docs.docker.com/engine/install/)
Verify Docker is running:
```bash theme={null}
docker ps
```
## Installation Steps
### 1. Install pipx
Install [pipx](https://pipx.pypa.io/stable/installation/) using your system's package manager or pip:
```bash theme={null}
python3 -m pip install --user pipx
python3 -m pipx ensurepath
```
Restart your terminal, then verify:
```bash theme={null}
pipx --version
```
### 2. Install agentsystems-sdk
```bash theme={null}
pipx install agentsystems-sdk
agentsystems --version
```
## Initialize and Start
```bash theme={null}
agentsystems init agent-platform
cd agent-platform
agentsystems up
```
Open your browser to `http://localhost:3001`
# Quick Start
Source: https://docs.agentsystems.ai/fortress/getting-started/quickstart
Deploy AgentSystems in 5 minutes
## System Requirements
AgentSystems requires:
* **Python 3.11 or higher**
* **Docker** (Docker Desktop on macOS, Docker Engine on Linux)
* **Operating System**: macOS or Ubuntu Linux
Run the installation script:
```bash theme={null}
curl -fsSL https://github.com/agentsystems/agentsystems/releases/latest/download/install.sh | sh
```
Create and enter your deployment directory:
```bash theme={null}
agentsystems init my-deployment
cd my-deployment
```
The init command prompts for:
* Langfuse credentials for observability
* Admin credentials for the UI
Launch all platform services:
```bash theme={null}
agentsystems up
```
This starts:
* Agent Control Plane (Gateway)
* AgentSystems UI at [http://localhost:3001](http://localhost:3001)
* PostgreSQL database
Download a small model for local testing:
```bash theme={null}
docker exec agentsystems-ollama-1 ollama pull gemma3:1b
```
This downloads a local AI model without needing API keys.
Open [http://localhost:3001](http://localhost:3001) in your browser to execute your first local agent.
## Stop the Platform
When you're done:
```bash theme={null}
agentsystems down
```
# Agent Index
Source: https://docs.agentsystems.ai/fortress/user-guide/agent-index
Future agent discovery platform
The Agent Index is a planned feature for discovering and deploying community agents.
The Agent Index is currently in development. This page describes the planned functionality.
## Vision
The Agent Index will simplify finding and deploying agents by providing:
* Browse available agents
* One-click agent deployment
* Community contributions
# Artifacts
Source: https://docs.agentsystems.ai/fortress/user-guide/artifacts
Understanding the artifacts system
The artifacts system uses separate file storage for each agent execution. Each thread has its own input and output directories.
Files are thread-scoped by design; cross-thread access is blocked by platform policy but should not be relied on as a hard security boundary.
## How Artifacts Work
Each agent execution gets a unique thread ID and isolated storage
Uploaded files are placed in the thread's input directory
Agent reads input files and generates output files
Results are written to the thread's output directory
Download output files via UI, CLI, or API
## File Structure
Each thread has this directory layout:
```
artifacts/
└── threads/
└── abc123-def456/ # Thread ID
├── input/ # Input files
│ ├── data.csv
│ └── config.json
└── output/ # Output files
├── results.csv
└── report.pdf
```
## Uploading Input Files
### Via UI
In the agent detail page at [http://localhost:3001](http://localhost:3001):
1. Click **Choose Files**
2. Select files to upload
3. Files appear in the input list
## Downloading Output Files
### Via UI
Navigate to the execution details to see output files. Click to download.
# Audit Logs
Source: https://docs.agentsystems.ai/fortress/user-guide/audit-logs
Hash-chained audit trail system
AgentSystems includes an audit trail feature that uses cryptographic hash chaining for agent executions.
Agent executions are logged with cryptographic hashing for audit purposes.
## How It Works
The audit system creates a hash-chained log of execution records:
System records agent executions automatically
Each log entry includes a SHA-256 hash of its contents
Each hash includes the previous entry's hash, creating a chain
Changes to past entries can be detected via hash verification (for tamper-evidence)
## Viewing Audit Logs
### Via UI
Navigate to **Executions** in the AgentSystems UI at [http://localhost:3001](http://localhost:3001).
The UI displays:
* Execution timeline
* Agent details
* Request/response data
* Hash verification (for tamper-evidence) status
* Filter and search options
## Audit Features
Can help detect modifications to past logs
Cryptographic hashing (for tamper-evidence) of execution history
Records chronological sequence of events
Uses SHA-256 hashing for verification (tamper-evidence)
# CLI Commands
Source: https://docs.agentsystems.ai/fortress/user-guide/cli-commands
SDK command reference
The AgentSystems SDK includes command-line tools for managing your platform deployment.
The `agentsystems` CLI includes platform management commands.
## Platform Management
### Lifecycle
Control the platform lifecycle with these commands:
```bash theme={null}
# Start all services
agentsystems up
# Start in detached mode (default)
agentsystems up --detach
# Start with fresh containers
agentsystems up --fresh
# Start without Langfuse tracing
agentsystems up --no-langfuse
```
The platform starts at:
* UI: [http://localhost:3001](http://localhost:3001)
* Gateway: [http://localhost:18080](http://localhost:18080)
```bash theme={null}
# Stop all services
agentsystems down
# Stop and remove volumes
agentsystems down --volumes
```
```bash theme={null}
# Quick restart
agentsystems restart
# Restart with fresh volumes
agentsystems restart --volumes
```
### Monitoring
Check platform status and view logs:
```bash theme={null}
# Show all container status
agentsystems status
# Check specific service
agentsystems status --service gateway
```
```bash theme={null}
# Stream all logs
agentsystems logs
# View gateway logs
agentsystems logs --service gateway
# Tail last 100 lines
agentsystems logs --tail 100
# Follow log output
agentsystems logs --follow
```
## Running Agents
Execute agents with JSON payloads and optional file uploads:
```bash theme={null}
agentsystems run hello-world-agent '{"date": "October 15, 1979"}'
```
```bash theme={null}
agentsystems run my-agent '{"format": "csv"}' \
--input-file data.csv
```
## Artifact Management
Access input and output files from agent executions:
```bash theme={null}
# Get output directory for a thread
agentsystems artifacts-path abc123-def456
# Get specific output file path
agentsystems artifacts-path abc123-def456 result.json
# Get input directory
agentsystems artifacts-path abc123-def456 --input
# Get specific input file
agentsystems artifacts-path abc123-def456 data.csv --input
```
## System Maintenance
Manage platform resources and updates:
```bash theme={null}
# Nuclear cleanup
agentsystems clean
# Skip Docker prune
agentsystems clean --no-prune-system
```
Removes all containers, volumes, and optionally prunes Docker.
```bash theme={null}
# Update core images
agentsystems update
```
Pulls latest versions of platform components.
## Command Reference
### Platform Commands
| Command | Description |
| ----------------------------- | ------------------------- |
| `agentsystems init [DIR]` | Initialize new deployment |
| `agentsystems up` | Start platform services |
| `agentsystems down` | Stop platform services |
| `agentsystems restart` | Restart platform |
| `agentsystems logs` | View service logs |
| `agentsystems status` | Check service status |
| `agentsystems run` | Execute an agent |
| `agentsystems artifacts-path` | Get artifact file paths |
| `agentsystems clean` | Deep clean system |
| `agentsystems update` | Update platform images |
| `agentsystems version` | Show SDK version |
| `agentsystems info` | Show diagnostics |
## Command Alias
For convenience, a shorter alias is available:
* `agntsys` → `agentsystems`
## Getting Help
All commands support `--help` to display detailed usage information, available options, and examples:
```bash theme={null}
# Show all available commands and global options
agentsystems --help
# Show options for running agents (payloads, file uploads, polling)
agentsystems run --help
# Show options for viewing logs (filtering, following, tail)
agentsystems logs --help
```
# Running Agents
Source: https://docs.agentsystems.ai/fortress/user-guide/running-agents
Execute agents via UI or CLI
Agents process requests with JSON payloads and optional file uploads. You can run them through the UI or CLI.
## Running via UI
Navigate to **Agents** in the AgentSystems UI at [http://localhost:3001](http://localhost:3001).
Browse available agents and click **Turn On** on your chosen agent (agents auto-start if invoked while off)
* Enter JSON payload in the request editor
* Upload input files if needed
* Review agent requirements
Click **Execute** to start execution
Watch real-time progress updates and logs
Download output files when complete
## Running via CLI
Use the SDK CLI to run agents programmatically. See [CLI Commands](/fortress/user-guide/cli-commands) for details.
## Request Structure
Every agent request includes:
JSON object with agent-specific parameters:
```json theme={null}
{
"action": "analyze",
"format": "csv",
"options": {
"verbose": true
}
}
```
Upload files for processing:
* Via UI: Drag & drop or browse
* Via CLI: Use `--input-file` flag
* Multiple files supported
* All common formats accepted
Unique identifier for the execution:
* Auto-generated if not provided
* Used to track progress
* Required for accessing artifacts
## Response Handling
Agents return structured responses:
```json theme={null}
{
"thread_id": "abc123-def456",
"status": "completed",
"progress": 100,
"messages": [
{
"type": "result",
"content": "Analysis complete"
}
],
"artifacts": [
"output/results.csv",
"output/report.pdf"
]
}
```
### Status Values
| Status | Description |
| ------------- | ---------------- |
| `pending` | Request queued |
| `in_progress` | Agent processing |
| `completed` | Success |
| `failed` | Error occurred |
## Accessing Output Files
After execution, download output files through the UI execution details page.
## Progress Tracking
Agents provide real-time progress updates in the UI.
## Error Handling
When agents fail, error details appear in the UI execution log.
# Troubleshooting
Source: https://docs.agentsystems.ai/fortress/user-guide/troubleshooting
Common issues and solutions
## Quick Fix
Most issues can be resolved by restarting the platform:
```bash theme={null}
agentsystems restart
```
This command stops and restarts all AgentSystems services, which often resolves:
* Connection issues
* Stuck agents
* UI not updating
* Configuration not applying
## Still Having Issues?
If restarting doesn't help:
1. Check logs: `agentsystems logs`
2. Review status: `agentsystems status`
3. Report issues: [GitHub Issues](https://github.com/agentsystems/agentsystems/issues)
# AgentSystems
Source: https://docs.agentsystems.ai/index
Infrastructure for AI agents
Audit trail infrastructure for AI agent operations. Dual-write architecture stores hashes to a shared ledger and raw logs to your own storage.
Self-hosted platform for discovering and running AI agents. Deploy containerized agents on your infrastructure with provider portability and audit logging.
# Hash Storage
Source: https://docs.agentsystems.ai/notary/configuration/hash-storage
Configure where cryptographic hashes are stored
Hash storage is where the SHA-256 hashes of your audit payloads are written. Only hashes and metadata are stored externally — raw data stays in your infrastructure.
You can use one or both options.
## Decentralized (Arweave)
Hashes are written to a public, append-only ledger. Not controlled by any single vendor.
```python theme={null}
from agentsystems_notary import ArweaveHashStorage, LocalKeySignerConfig
arweave_storage = ArweaveHashStorage(
namespace="tenant_a1b2c3d4", # anonymous tenant identifier
signer=LocalKeySignerConfig(
private_key_path="/path/to/arweave-key.pem",
),
# bundler_url defaults to ArDrive Turbo
)
```
### Parameters
| Parameter | Required | Description |
| ------------- | -------- | --------------------------------------------------------------------------------- |
| `namespace` | Yes | Anonymous tenant identifier (written to public ledger — do not use company names) |
| `signer` | Yes | Signing configuration (see [Signers](/notary/configuration/signing)) |
| `bundler_url` | No | Arweave bundler endpoint (defaults to ArDrive Turbo) |
### Verification
Verify with the open-source CLI — no account required:
```bash theme={null}
npm install -g agentsystems-verify
agentsystems-verify --logs logs.zip
```
See [Independent Verification](/notary/verification/arweave) for full documentation.
## Custodied (AgentSystems)
Hashes are written to AgentSystems' write-once compliance storage. Provides a vendor relationship for enterprise compliance and procurement.
```python theme={null}
from agentsystems_notary import CustodiedHashStorage
custodied_storage = CustodiedHashStorage(
api_key="sk_asn_prod_...",
slug="customer-123",
)
```
### Parameters
| Parameter | Required | Description |
| --------- | -------- | --------------------------------------------------------- |
| `api_key` | Yes | AgentSystems API key (`sk_asn_test_*` or `sk_asn_prod_*`) |
| `slug` | Yes | Tenant slug (human-readable identifier) |
| `api_url` | No | API endpoint (defaults to production) |
### Get an API Key
1. Sign up at [notary.agentsystems.ai](https://notary.agentsystems.ai)
2. From the Dashboard, click **Add** under API Keys
3. Name your key and select environment
4. Copy and save the key — it's only shown once
### Verification
Verify via the [Verify UI](https://verify.agentsystems.ai) or see [Verification Guide](/notary/verification/guide).
## Using Both
You can write hashes to both Arweave and custodied storage:
```python theme={null}
notary = LangChainNotary(
raw_payload_storage=raw_payload_storage,
hash_storage=[
ArweaveHashStorage(...),
CustodiedHashStorage(...),
],
)
```
This provides independent verification via Arweave plus a vendor relationship via AgentSystems.
# Raw Payload Storage
Source: https://docs.agentsystems.ai/notary/configuration/raw-payload-storage
Configure where full audit payloads are stored
Raw payload storage is where the full JSON payload of every LLM interaction is written. This is your storage — you maintain full control.
## AWS S3
```python theme={null}
from agentsystems_notary import RawPayloadStorage, AwsS3StorageConfig
raw_payload_storage = RawPayloadStorage(
storage=AwsS3StorageConfig(
bucket_name="acme-corp-audit-logs",
aws_access_key_id="AKIA...",
aws_secret_access_key="...",
aws_region="us-east-1", # default
),
)
```
### Required IAM Permissions
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["s3:PutObject", "s3:GetObject", "s3:ListBucket"],
"Resource": [
"arn:aws:s3:::acme-corp-audit-logs",
"arn:aws:s3:::acme-corp-audit-logs/*"
]
}]
}
```
## GCP Cloud Storage
Coming soon
```python theme={null}
from agentsystems_notary import RawPayloadStorage, GcpCloudStorageConfig
raw_payload_storage = RawPayloadStorage(
storage=GcpCloudStorageConfig(
bucket_name="acme-corp-audit-logs",
credentials_path="/path/to/service-account.json", # optional, uses ADC if not provided
),
)
```
## Azure Blob Storage
Coming soon
```python theme={null}
from agentsystems_notary import RawPayloadStorage, AzureBlobStorageConfig
raw_payload_storage = RawPayloadStorage(
storage=AzureBlobStorageConfig(
container_url="https://acme.blob.core.windows.net",
container_name="audit-logs",
),
)
```
## Storage Path Structure
Payloads are stored with the following path structure:
```
{env}/{namespace}/{YYYY}/{MM}/{DD}/{hash}.json
```
* `env`: `arweave`, `prod`, or `test`
* `namespace`: Your tenant identifier
* `hash`: SHA-256 hash of the canonical payload
# Signers
Source: https://docs.agentsystems.ai/notary/configuration/signing
Configure signing for Arweave hash storage
Signers are used to cryptographically sign data items before uploading to Arweave. All signers use RSA-4096 keys with PSS padding.
## Local Key
For development and testing. Generate a key with:
```bash theme={null}
openssl genrsa -out arweave-key.pem 4096
```
```python theme={null}
from agentsystems_notary import LocalKeySignerConfig
# From file path
signer = LocalKeySignerConfig(
private_key_path="/path/to/arweave-key.pem",
)
# Or from environment variable
signer = LocalKeySignerConfig(
private_key_env_var="ARWEAVE_PRIVATE_KEY",
)
```
Local keys are for development and testing only. Use a cloud key management service in production.
## AWS KMS
```python theme={null}
from agentsystems_notary import AwsKmsSignerConfig
signer = AwsKmsSignerConfig(
kms_key_arn="arn:aws:kms:us-east-1:123456789:key/abcd-1234-...",
aws_access_key_id="AKIA...",
aws_secret_access_key="...",
aws_region="us-east-1", # default
)
```
### KMS Key Requirements
Create an asymmetric RSA-4096 key with:
* Key spec: `RSA_4096`
* Key usage: `SIGN_VERIFY`
* Signing algorithm: `RSASSA_PSS_SHA_256`
### Required IAM Permissions
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["kms:Sign", "kms:GetPublicKey"],
"Resource": "arn:aws:kms:us-east-1:123456789:key/abcd-1234-..."
}]
}
```
## GCP Cloud KMS
Coming soon
```python theme={null}
from agentsystems_notary import GcpKmsSignerConfig
signer = GcpKmsSignerConfig(
key_resource_name="projects/.../locations/.../keyRings/.../cryptoKeys/.../cryptoKeyVersions/...",
credentials_path="/path/to/service-account.json", # optional, uses ADC if not provided
)
```
## Azure Key Vault
Coming soon
```python theme={null}
from agentsystems_notary import AzureKeyVaultSignerConfig
signer = AzureKeyVaultSignerConfig(
vault_url="https://acme-vault.vault.azure.net",
key_name="arweave-signing-key",
key_version="abc123", # optional, uses latest if not provided
)
```
# Introduction
Source: https://docs.agentsystems.ai/notary/getting-started/index
Third-party attestation for AI agent operations
AgentSystems Notary provides independent verification of your AI system's behavior. When buyers ask "how do we trust your AI logs?", you have an answer.
## How It Works
1. **Record** - The SDK captures LLM interactions as they happen
2. **Dual-Write** - Raw logs go to your S3 bucket. SHA-256 hashes go to your chosen storage.
3. **Verify** - Anyone with an audit ticket can verify logs
## Hash Storage Options
Notary supports two hash storage methods. You can use one or both.
| Option | Description | Verification |
| --------- | ---------------------------------- | ----------------------------------------------------------------------------- |
| Arweave | Hashes stored on public blockchain | [Independent verification](/notary/verification/arweave) with open-source CLI |
| Custodied | Hashes stored by AgentSystems API | Via [portal](https://verify.agentsystems.ai) |
**Arweave** provides decentralized, permanent storage on a public blockchain. Verification requires no AgentSystems infrastructure — anyone can verify using the open-source `agentsystems-verify` CLI. No vendor lock-in.
**Custodied** is a managed option if you prefer AgentSystems to handle the complexity. Verify through our portal.
## Components
| Component | URL | Purpose |
| ------------------- | -------------------------------------------------------- | ----------------------------------------------------- |
| Dashboard | [notary.agentsystems.ai](https://notary.agentsystems.ai) | View tenants, manage API keys, generate audit tickets |
| Verification Portal | [verify.agentsystems.ai](https://verify.agentsystems.ai) | Verify logs and download attestation packets |
| SDK | [PyPI](https://pypi.org/project/agentsystems-notary/) | Python SDK for LangChain and CrewAI |
| Verify CLI | [npm](https://www.npmjs.com/package/agentsystems-verify) | Open-source CLI for Arweave verification |
## Key Concepts
**Tenants** represent your customers. They're auto-discovered when the SDK logs its first interaction with a given slug. You don't need to create them in advance.
**Audit Tickets** are signed tokens that grant access to verify logs for a specific tenant and date range. They don't contain the hashes themselves — they authorize the verification portal to check logs against AgentSystems records.
**Attestation Packets** are self-contained proof bundles you can share with customers, compliance teams, or regulators. They contain the logs, audit ticket, a signed attestation certificate, and instructions for independent signature verification — everything needed to confirm the logs were checked against AgentSystems records.
End-to-end tutorial: signup → integration → verification
# Quickstart
Source: https://docs.agentsystems.ai/notary/getting-started/quickstart
Add independently verifiable audit logging to your AI agents
## 1. Set Up Your S3 Bucket
The SDK writes raw logs directly to your S3 bucket — you maintain full control.
1. Create an S3 bucket (names are globally unique, so include your company name — e.g., `acme-corp-raw-ai-logs`)
2. Create the following IAM policy:
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["s3:PutObject", "s3:GetObject", "s3:ListBucket"],
"Resource": [
"arn:aws:s3:::acme-corp-raw-ai-logs",
"arn:aws:s3:::acme-corp-raw-ai-logs/*"
]
}]
}
```
3. Create an IAM user and attach the policy
4. Generate access keys for the user (select "Application running outside AWS") and save them
## 2. Install the SDK
```bash theme={null}
mkdir notary-demo && cd notary-demo
python3 -m venv .venv
source .venv/bin/activate
pip install agentsystems-notary langchain-anthropic python-dotenv
```
```bash theme={null}
mkdir notary-demo && cd notary-demo
python3 -m venv .venv
source .venv/bin/activate
pip install agentsystems-notary crewai python-dotenv
```
## 3. Configure Environment
Create a `.env` file:
```bash theme={null}
# AWS credentials for your S3 bucket
ORG_AWS_S3_BUCKET_NAME=acme-corp-raw-ai-logs
ORG_AWS_S3_ACCESS_KEY_ID=...
ORG_AWS_S3_SECRET_ACCESS_KEY=...
ORG_AWS_S3_REGION=us-east-1
# Arweave hash storage
ARWEAVE_BUNDLER_URL=https://node2.bundlr.network
ARWEAVE_PRIVATE_KEY_PATH=path/to/rsa-4096-private.pem
# Your LLM provider
ANTHROPIC_API_KEY=...
```
## 4. Integrate the SDK
Create `test_langchain.py`:
```python theme={null}
import os
from dotenv import load_dotenv
from agentsystems_notary import (
LangChainNotary,
RawPayloadStorage,
ArweaveHashStorage,
LocalKeySignerConfig,
AwsS3StorageConfig,
)
from langchain_anthropic import ChatAnthropic
load_dotenv()
# Where full audit payloads are stored (your S3 bucket)
raw_payload_storage = RawPayloadStorage(
storage=AwsS3StorageConfig(
bucket_name=os.environ["ORG_AWS_S3_BUCKET_NAME"],
aws_access_key_id=os.environ["ORG_AWS_S3_ACCESS_KEY_ID"],
aws_secret_access_key=os.environ["ORG_AWS_S3_SECRET_ACCESS_KEY"],
aws_region=os.environ["ORG_AWS_S3_REGION"],
),
)
# Where hashes are stored — Arweave for independent verification
hash_storage = [
ArweaveHashStorage(
namespace="my_namespace",
signer=LocalKeySignerConfig(
private_key_path=os.environ["ARWEAVE_PRIVATE_KEY_PATH"],
),
bundler_url=os.environ["ARWEAVE_BUNDLER_URL"],
),
]
# Initialize notary
notary = LangChainNotary(
raw_payload_storage=raw_payload_storage,
hash_storage=hash_storage,
debug=True,
)
# Add to any LangChain model
model = ChatAnthropic(
model="claude-sonnet-4-5-20250929",
api_key=os.environ["ANTHROPIC_API_KEY"],
callbacks=[notary],
)
# All LLM calls are now logged
response = model.invoke("What is 2 + 2?")
print(response.content)
```
Run it:
```bash theme={null}
python test_langchain.py
```
Create `test_crewai.py`:
```python theme={null}
import os
from dotenv import load_dotenv
from agentsystems_notary import (
CrewAINotary,
RawPayloadStorage,
ArweaveHashStorage,
LocalKeySignerConfig,
AwsS3StorageConfig,
)
from crewai import Agent, Task, Crew, LLM
load_dotenv()
# Where full audit payloads are stored (your S3 bucket)
raw_payload_storage = RawPayloadStorage(
storage=AwsS3StorageConfig(
bucket_name=os.environ["ORG_AWS_S3_BUCKET_NAME"],
aws_access_key_id=os.environ["ORG_AWS_S3_ACCESS_KEY_ID"],
aws_secret_access_key=os.environ["ORG_AWS_S3_SECRET_ACCESS_KEY"],
aws_region=os.environ["ORG_AWS_S3_REGION"],
),
)
# Where hashes are stored — Arweave for independent verification
hash_storage = [
ArweaveHashStorage(
namespace="my_namespace",
signer=LocalKeySignerConfig(
private_key_path=os.environ["ARWEAVE_PRIVATE_KEY_PATH"],
),
bundler_url=os.environ["ARWEAVE_BUNDLER_URL"],
),
]
# Initialize notary (hooks register automatically)
notary = CrewAINotary(
raw_payload_storage=raw_payload_storage,
hash_storage=hash_storage,
debug=True,
)
# Create LLM
llm = LLM(
model="anthropic/claude-sonnet-4-5-20250929",
api_key=os.environ["ANTHROPIC_API_KEY"],
)
# Create agent and task
agent = Agent(
role="Research Analyst",
goal="Answer questions accurately",
backstory="You are an expert analyst.",
llm=llm,
)
task = Task(
description="What is 2 + 2?",
expected_output="The answer to the math question",
agent=agent,
)
crew = Crew(agents=[agent], tasks=[task])
# All LLM calls are now logged
result = crew.kickoff()
print(result)
```
Run it:
```bash theme={null}
python test_crewai.py
```
With `debug=True`, you'll see confirmation that the log was written to S3 and the hash was uploaded to Arweave.
## 5. Verify
Anyone can verify your logs using the open-source CLI — no account required:
```bash theme={null}
npm install -g agentsystems-verify
```
```bash theme={null}
agentsystems-verify \
--namespace my_namespace \
--start 2026-01-01 \
--end 2026-01-31 \
--logs logs.zip
```
See [Independent Verification](/notary/verification/arweave) for full CLI documentation.
## Signer Options
The examples above use a local RSA-4096 private key. You can also use managed key services:
* `LocalKeySignerConfig` — Local RSA-4096 private key (PEM file or env var)
* `AwsKmsSignerConfig` — AWS KMS managed key
* `GcpKmsSignerConfig` — GCP Cloud KMS managed key
* `AzureKeyVaultSignerConfig` — Azure Key Vault managed key
***
## Using Custodied Storage (Optional)
If you prefer AgentSystems to manage hash storage, you can use our custodied option instead of (or in addition to) Arweave.
### Create Account
Go to [notary.agentsystems.ai](https://notary.agentsystems.ai) and sign up.
### Generate an API Key
1. From the Dashboard, click **Add** under API Keys
2. Name your key and select environment
3. Copy and save the key — it's only shown once
### Add to Environment
```bash theme={null}
AGENTSYSTEMS_NOTARY_API_KEY=sk_asn_test_...
```
### Add Custodied Hash Storage
```python theme={null}
from agentsystems_notary import CustodiedHashStorage
hash_storage = [
ArweaveHashStorage(...), # Keep Arweave for independent verification
CustodiedHashStorage(
api_key=os.environ["AGENTSYSTEMS_NOTARY_API_KEY"],
slug="customer-123",
),
]
```
### Verify via Portal
1. Go to [notary.agentsystems.ai](https://notary.agentsystems.ai) → Tenants → Generate Verification Ticket
2. Export logs from your S3 bucket
3. Upload both to [verify.agentsystems.ai](https://verify.agentsystems.ai)
See [Verification Guide](/notary/verification/guide) for full portal documentation.
# Independent Verification
Source: https://docs.agentsystems.ai/notary/verification/arweave
Verify Arweave-notarized logs with open-source tooling
## Overview
For logs notarized to the Arweave blockchain, you can verify them independently using our open-source verification tool. This approach:
* Requires no API keys or AgentSystems infrastructure
* Is fully open-source and auditable
* Queries the public Arweave network directly
## Prerequisites
* Logs exported from your S3 bucket (ZIP file)
* Verification ticket (generated from notary dashboard or your records)
## Installation
```bash theme={null}
npm install -g agentsystems-verify
```
## CLI Usage
### With a ticket file
```bash theme={null}
agentsystems-verify --ticket ticket.json --logs logs.zip
```
### With CLI flags
```bash theme={null}
agentsystems-verify \
--owner \
--namespace my_namespace \
--start 2026-01-01 \
--end 2026-01-31 \
--logs logs.zip
```
### Interactive mode
```bash theme={null}
agentsystems-verify --logs logs.zip
# Prompts for missing values
```
## Understanding Results
| Result | Meaning |
| ----------- | -------------------------------------- |
| Verified | Found in ZIP and on Arweave blockchain |
| Unnotarized | In ZIP but not on Arweave |
| Missing | On Arweave but not in ZIP |
## Library Usage (JavaScript/TypeScript)
```typescript theme={null}
import { verify, validateTicket } from "agentsystems-verify";
import { readFileSync } from "fs";
const ticket = validateTicket(JSON.parse(readFileSync("ticket.json", "utf-8")));
const zipBuffer = readFileSync("logs.zip");
const results = await verify(ticket, zipBuffer, {
onProgress: (msg) => console.log(msg),
});
console.log(`Verified: ${results.verified.length}`);
console.log(`Unnotarized: ${results.unnotarized.length}`);
console.log(`Missing: ${results.missing.length}`);
```
## How It Works
1. Extracts JSON files from the ZIP archive
2. Canonicalizes and hashes each file (SHA-256)
3. Queries Arweave blockchain for matching transactions
4. Compares local hashes against blockchain records
## Source Code
[github.com/agentsystems/agentsystems-verify](https://github.com/agentsystems/agentsystems-verify)
# Verification
Source: https://docs.agentsystems.ai/notary/verification/guide
How to verify log integrity
This guide covers verification for custodied hash storage (AgentSystems API).
For Arweave (decentralized) verification, see [Independent Verification](/notary/verification/arweave).
Verification compares logs against AgentSystems records to identify any discrepancies. Anyone with an audit ticket can verify — your customers, their compliance teams, or third-party reviewers.
## What You Need
| Item | How to Get It |
| ---------------- | ---------------------------------------------------------------------------------------- |
| **Audit Ticket** | Generate from [notary.agentsystems.ai](https://notary.agentsystems.ai) → Tenants → Audit |
| **Logs ZIP** | Export from your S3 bucket (commands shown in the Audit modal) |
The audit ticket is a signed token that grants access to check logs against AgentSystems records for a specific tenant and date range.
## Running Verification
1. Go to [verify.agentsystems.ai](https://verify.agentsystems.ai)
2. Upload the audit ticket (`.json`)
3. Upload the logs (`.zip`)
4. Click **Start Verification**
No account is required to run verification.
## Understanding Results
| Result | Meaning |
| ------------------------ | -------------------------------------------------------- |
| **Verified Records** | Records in the ZIP that match AgentSystems records |
| **Unrecognized Records** | Records in the ZIP that weren't recorded by AgentSystems |
| **Missing Records** | Records that AgentSystems recorded but aren't in the ZIP |
## Attestation Packets
After verification, download an attestation packet — a self-contained proof bundle you can share with customers, compliance teams, or regulators. Recipients can verify the cryptographic signature themselves without needing to re-run verification or trust your word.
## Verifying the Signature
The attestation certificate is signed with AgentSystems' notary key. To verify independently:
```bash theme={null}
# Download the public key
curl -o notary.pem https://verify-api.agentsystems.ai/.well-known/notary.pem
# Verify the signature
openssl dgst -sha256 -verify notary.pem -signature attestation.pdf.sig attestation.pdf
```
Expected output: `Verified OK`