Agentstr CLI

The agentstr command-line tool lets you deploy a single-file Python “agent” to AWS ECS Fargate, Google Kubernetes Engine or Azure Container Instances with zero infrastructure code.

Prerequisites

You need Docker running for all providers.

Provider

CLI tools

Environment variables

AWS

aws

AWS_PROFILE or standard AWS credential env vars

GCP

gcloud, kubectl

GCP_PROJECT

Azure

az

AZURE_SUBSCRIPTION_ID

Ensure each CLI is authenticated and Docker can push to the relevant registry.

Installation

The CLI is installed automatically when you install the SDK with the cli extra:

uv add agentstr-sdk[cli]   # or: pip install "agentstr-sdk[cli]"

This places an agentstr executable on your $PATH.

Basic Commands

    • deploy -f path/to/config.yaml

    • Build Docker image, push and deploy app.py as a container service.

    • list -f path/to/config.yaml

    • List existing deployments.

    • logs -f path/to/config.yaml

    • Stream recent logs from a deployment.

    • destroy -f path/to/config.yaml

    • Tear down the deployment/service.

Configuration

A minimal template you can reuse across commands. Pass it anywhere on the command line with -f/--config or set the AGENTSTR_CONFIG env var.

provider: aws            # aws | gcp | azure
file_path: app/agent.py  # Python entry-point
name: my-agent           # optional – deployment name
cpu: 256                 # optional – CPU units / cores
memory: 512              # optional – memory in MiB
extra_pip_deps:          # optional – extra pip packages
  - openai
  - langchain
env:                     # optional – env vars
  MY_VAR: 123
secrets:                 # optional – provider secret refs
  MY_SECRET: arn:aws:secretsmanager:us-west-2:123:secret:MY_SECRET
Key fields

Field

Type

Description

provider

string

Required. One of aws, gcp, azure.

file_path

path

Required. Python file executed inside the container.

name

string

Deployment/service name. Defaults to filename stem.

cpu

int

CPU units / cores to allocate.

memory

int

Memory in MiB.

env

map

Environment variables passed to the container.

secrets

map

Provider-managed secret references (ARN/URI/path).

extra_pip_deps

list

Extra PyPI packages installed into the image before deploy.

Cloud Provider Environment Variables

# AWS (assuming aws is authenticated)
export AWS_PROFILE=your-profile

# GCP (assuming gcloud is authenticated)
export GCP_PROJECT=your-project

# Azure (assuming az is authenticated)
export AZURE_SUBSCRIPTION_ID=your-subscription-id

CLI Commands

# Deploy / update
agentstr deploy -f configs/aws.yml

# View logs
agentstr logs -f configs/aws.yml

# List deployments
agentstr list -f configs/aws.yml

# Destroy
agentstr destroy -f configs/aws.yml

CI/CD - GitHub Actions

The repository ships with ready-made workflows to deploy your agent to AWS, GCP or Azure on every push. Copy the desired file, set the required secrets and you are ready to deploy.

Cloud

Workflow file

Purpose

AWS

deploy-aws.yml

Installs dependencies, authenticates with AWS and runs agentstr deploy -f configs/aws.yml.

GCP

deploy-gcp.yml

Authenticates with a service-account key, installs kubectl / GKE plugin and deploys using configs/gcp.yml.

Azure

deploy-azure.yml

Logs in with az and deploys using configs/azure.yml.

Below are the workflow definitions for reference:

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      - "configs/aws.yml"
13      - ".github/workflows/deploy-aws.yml"
14
15jobs:
16  deploy:
17    runs-on: ubuntu-latest
18
19    steps:
20      - uses: actions/checkout@v4
21
22      - name: Install uv
23        uses: astral-sh/setup-uv@v5
24
25      - name: "Set up Python"
26        uses: actions/setup-python@v5
27        with:
28          python-version-file: ".python-version"
29          
30      - name: Install the project
31        run: uv sync --all-extras --dev
32
33      - name: Deploy to AWS
34        env:
35          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
36          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
37          AWS_DEFAULT_REGION: ${{ secrets.AWS_REGION }}
38        run: uv run agentstr deploy -f configs/aws.yml

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      - "configs/gcp.yml"
12      - ".github/workflows/deploy-gcp.yml"
13
14jobs:
15  deploy:
16    runs-on: ubuntu-latest
17
18    steps:
19      - uses: actions/checkout@v4
20
21      - name: Install uv
22        uses: astral-sh/setup-uv@v5
23
24      - name: "Set up Python"
25        uses: actions/setup-python@v5
26        with:
27          python-version-file: ".python-version"
28
29      - name: Install the project
30        run: uv sync --all-extras --dev
31
32      - name: Authenticate to GCP
33        uses: google-github-actions/auth@v2
34        with:
35          credentials_json: ${{ secrets.GCP_SERVICE_ACCOUNT_KEY }}
36
37      # Get the GKE credentials so we can deploy to the cluster
38      - uses: google-github-actions/get-gke-credentials@db150f2cc60d1716e61922b832eae71d2a45938f
39        with:
40          cluster_name: agentstr-cluster
41          location: us-central1-b
42          credentials_json: ${{ secrets.GCP_SERVICE_ACCOUNT_KEY }}
43
44      - name: Install gke-gcloud-auth-plugin
45        uses: simenandre/setup-gke-gcloud-auth-plugin@v1 # Or the latest version
46
47      - name: Deploy to GCP
48        env:
49          GCP_PROJECT: ${{ secrets.GCP_PROJECT }}
50        run: uv run agentstr deploy -f configs/gcp.yml

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      - "configs/azure.yml"
12      - ".github/workflows/deploy-azure.yml"
13
14jobs:
15  deploy:
16    runs-on: ubuntu-latest
17
18    steps:
19      - uses: actions/checkout@v4
20
21      - name: Install uv
22        uses: astral-sh/setup-uv@v5
23
24      - name: "Set up Python"
25        uses: actions/setup-python@v5
26        with:
27          python-version-file: ".python-version"
28
29      - name: Install the project
30        run: uv sync --all-extras --dev
31
32      - name: Azure Login
33        uses: azure/login@v2
34        with:
35          creds: ${{ secrets.AZURE_CREDENTIALS }}
36
37      - name: Deploy to Azure
38        env:
39          AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
40        run: uv run agentstr deploy -f configs/azure.yml