Cloud & CI/CD

The Agentstr SDK provides a powerful command-line interface (CLI) to deploy your agents to the cloud with minimal configuration. This guide covers how to deploy to AWS, Google Cloud, and Azure, and set up automated CI/CD pipelines with GitHub Actions.

Note

The agentstr CLI is designed to abstract away the complexities of cloud infrastructure. You don’t need to write any Terraform or CloudFormation templates.

Prerequisites

Before you can deploy, make sure you have the following tools installed and configured:

You must also be authenticated with your chosen cloud provider and have permissions to push to its container registry (e.g., ECR, GCR, ACR).

Configuration File

All deployment commands are driven by a YAML configuration file. This file tells the CLI which provider to use, where your agent’s code is, and how to configure the deployment.

Here is an example of a complete configuration file:

config.yaml
# Cloud provider: aws, gcp, azure, or docker (for local deployments)
provider: aws  # Can also be set by AGENTSTR_PROVIDER environment variable

# Path to your agent's main Python file
file_path: my-agent/agent.py

# Name for your deployment/service (optional)
name: my-agent

# Database (optional but recommended for production agents)
database: true

# Resource allocation (optional)
cpu: 256     # CPU units (AWS/Azure) or cores (GCP)
memory: 512  # Memory in MiB

# Extra PyPI packages to install (optional)
extra_pip_deps:
  - openai
  - langchain

# Environment variables for your agent (optional)
env:
  NOSTR_RELAYS: wss://relay.primal.net,wss://relay.damus.io,wss://nostr.mom

# References to secrets managed by your cloud provider (optional)
secrets:
  NOSTR_NSEC: arn:aws:secretsmanager:us-west-2:123456789012:secret:NOSTR_NSEC-AbCdEf
  NWC_CONN_STR: arn:aws:secretsmanager:us-west-2:123456789012:secret:NWC_CONN_STR-AbCdEf

# Path to a .env file for loading secrets (optional)
env_file: my-agent/.env

Tip

You can pass the configuration file to any command using the -f or --config flag. Alternatively, set the AGENTSTR_CONFIG environment variable.

Note

Configuration values are resolved with the following precedence (highest to lowest). If a variable is specified in multiple locations, the one with the highest precedence is used.

  1. Direct command-line flags (e.g., --env or --secret)

  2. The env or secrets maps in the YAML configuration file

  3. Variables defined in the env_file

Variables from the env_file and the secrets map are always treated as secrets and are uploaded to your cloud provider’s secret manager. Variables from the env map and the --env flag are passed as plaintext environment variables.

CLI Commands

Once your configuration file is ready, you can use the following commands to manage your deployment.

Deploy or Update an Agent

The deploy command builds a Docker image of your agent, pushes it to your cloud provider’s registry, and deploys it as a service.

agentstr deploy -f path/to/config.yaml

View Agent Logs

To stream logs from your running agent, use the logs command:

agentstr logs -f path/to/config.yaml

List Deployments

You can list all active agent deployments managed by the CLI:

agentstr list -f path/to/config.yaml

Destroy a Deployment

To tear down a deployment and delete all associated resources, use the destroy command:

agentstr destroy -f path/to/config.yaml

Note

For more information on the CLI commands, see the Agentstr CLI module.

Local Docker Deployment

Docker deployments are ideal for local development and testing. They allow you to run Agentstr applications in isolated containers on your machine without needing cloud credentials or internet access.

Prerequisites:

  • Docker and Docker Compose must be installed on your system.

  • Ensure the Agentstr CLI is installed (pip install agentstr-sdk[cli]).

Steps:

  1. Set the provider:

    export AGENTSTR_PROVIDER=docker

  2. Deploy your application:

    agentstr deploy -f path/to/deploy.yml

    This will create a Docker container for your application and, if needed, a Postgres database container. Both are networked together automatically.

  3. List deployments:

    agentstr list

    You’ll see only Agentstr-related containers prefixed with agentstr-.

  4. View logs:

    agentstr logs -f path/to/deploy.yml

  5. Destroy the deployment when done:

    agentstr destroy -f path/to/deploy.yml

Benefits of Docker Deployment:

  • Isolation: Each deployment runs in its own container, preventing dependency conflicts.

  • Consistency: Mimics production environment setup with containers.

  • Speed: No cloud latency or credential setup needed.

  • Cost: Free for local development.

Limitations:

  • Not suitable for production due to lack of scalability and persistence compared to cloud providers.

  • Requires local Docker setup and resources.

Note

If you encounter connection issues between your application and database, ensure both containers are running and on the same network. The Agentstr CLI handles this automatically, but manual Docker inspection can confirm (docker ps, docker network ls).

Nostr Metadata

When deploying your Agentstr application to the cloud, if you have a nostr-metadata.yml file in the same directory as your main application file, it will be automatically deployed along with your application. This file contains metadata for your application’s Nostr profile, which will be used by the Agentstr SDK to update and broadcast your profile information on the Nostr network.

For more information on Nostr metadata and how to configure it, refer to Nostr Metadata.

CI/CD with GitHub Actions

The Agentstr SDK includes ready-to-use GitHub Actions workflows to automate your deployments. On every push to your repository, these workflows can build and deploy your agent to the cloud.

To get started, copy one of the following workflow files into the .github/workflows/ directory of your repository and configure the required secrets in your GitHub project settings.

Available Workflows

Cloud

Workflow File

Description

AWS

deploy-aws.yml

Authenticates with AWS and runs agentstr deploy.

GCP

deploy-gcp.yml

Authenticates with a GCP service account and runs agentstr deploy.

Azure

deploy-azure.yml

Logs in with Azure credentials and runs agentstr deploy.
Required Secrets

Cloud

Secret Name

Description

AWS

AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION

AWS credentials and region for authentication.

GCP

GCP_PROJECT, GCP_SERVICE_ACCOUNT_KEY

GCP project ID and service account key for authentication.

Azure

AZURE_SUBSCRIPTION_ID, AZURE_CREDENTIALS

Azure subscription ID and credentials for authentication.

Workflow Examples

For reference, here are the contents of the workflow files. Make sure to update the AGENTSTR_CONFIG environment variable to point to your Agentstr configuration file.

AWS

 1# GitHub Actions workflow: Deploy to AWS with agentstr-cli
 2
 3name: deploy-aws
 4
 5# Trigger manually or when the AWS config changes
 6on:
 7  workflow_dispatch:
 8  push:
 9    branches:
10      - main
11    paths:
12      - "getting_started/hello_world/deploy.yml"
13      - ".github/workflows/deploy-aws.yml"
14
15env: 
16  AGENTSTR_PROVIDER: aws
17  AGENTSTR_CONFIG: configs/aws.yml  # Change this to your config file
18
19jobs:
20  deploy:
21    runs-on: ubuntu-latest
22
23    steps:
24      - uses: actions/checkout@v4
25
26      - name: Install uv
27        uses: astral-sh/setup-uv@v5
28
29      - name: "Set up Python"
30        uses: actions/setup-python@v5
31        with:
32          python-version-file: ".python-version"
33          
34      - name: Install the project
35        run: uv sync --all-extras --dev
36
37      - name: Deploy to AWS
38        env:
39          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
40          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
41          AWS_DEFAULT_REGION: ${{ secrets.AWS_REGION }}
42        run: uv run agentstr deploy -f $AGENTSTR_CONFIG

GCP

 1# GitHub Actions workflow: Deploy to Google Cloud Run with agentstr-cli
 2
 3name: deploy-gcp
 4
 5on:
 6  workflow_dispatch:
 7  push:
 8    branches:
 9      - main
10    paths:
11      - "getting_started/hello_world/deploy.yml"
12      - ".github/workflows/deploy-gcp.yml"
13
14env: 
15  AGENTSTR_PROVIDER: gcp
16  AGENTSTR_CONFIG: configs/gcp.yml  # Change this to your config file
17
18jobs:
19  deploy:
20    runs-on: ubuntu-latest
21
22    steps:
23      - uses: actions/checkout@v4
24
25      - name: Install uv
26        uses: astral-sh/setup-uv@v5
27
28      - name: "Set up Python"
29        uses: actions/setup-python@v5
30        with:
31          python-version-file: ".python-version"
32
33      - name: Install the project
34        run: uv sync --all-extras --dev
35
36      - name: Authenticate to GCP
37        uses: google-github-actions/auth@v2
38        with:
39          credentials_json: ${{ secrets.GCP_SERVICE_ACCOUNT_KEY }}
40
41      # Get the GKE credentials so we can deploy to the cluster
42      - uses: google-github-actions/get-gke-credentials@db150f2cc60d1716e61922b832eae71d2a45938f
43        with:
44          cluster_name: agentstr-cluster
45          location: us-central1-b
46          credentials_json: ${{ secrets.GCP_SERVICE_ACCOUNT_KEY }}
47
48      - name: Install gke-gcloud-auth-plugin
49        uses: simenandre/setup-gke-gcloud-auth-plugin@v1 # Or the latest version
50
51      - name: Deploy to GCP
52        env:
53          GCP_PROJECT: ${{ secrets.GCP_PROJECT }}
54        run: uv run agentstr deploy -f $AGENTSTR_CONFIG

Azure

 1# GitHub Actions workflow: Deploy to Azure Container Instances with agentstr-cli
 2
 3name: deploy-azure
 4
 5on:
 6  workflow_dispatch:
 7  push:
 8    branches:
 9      - main
10    paths:
11      - "getting_started/hello_world/deploy.yml"
12      - ".github/workflows/deploy-azure.yml"
13
14env: 
15  AGENTSTR_PROVIDER: azure
16  AGENTSTR_CONFIG: configs/azure.yml  # Change this to your config file
17
18jobs:
19  deploy:
20    runs-on: ubuntu-latest
21
22    steps:
23      - uses: actions/checkout@v4
24
25      - name: Install uv
26        uses: astral-sh/setup-uv@v5
27
28      - name: "Set up Python"
29        uses: actions/setup-python@v5
30        with:
31          python-version-file: ".python-version"
32
33      - name: Install the project
34        run: uv sync --all-extras --dev
35
36      - name: Azure Login
37        uses: azure/login@v2
38        with:
39          creds: ${{ secrets.AZURE_CREDENTIALS }}
40
41      - name: Deploy to Azure
42        env:
43          AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
44        run: uv run agentstr deploy -f $AGENTSTR_CONFIG