Skip to main content

Part 1 - setting up your directors

To get started with Sandgarden you need a Director running to execute your code. The Director is a core component that executes your code and manages workflows. Directors:

  • Organize and route workflows in real-time
  • Coordinate complex batch processes
  • Ensure your code has access to required infrastructure

To follow along with the deployment instructions below, clone the Getting started repository here.

Running Directors​

There are two ways to run directors:

In both cases, start by generating a director API key. You can do this from the UI dashboard, or via the CLI. Once you have this in hand, proceed to one (or both) of the two deployment modes below.

Local development mode​

note

These instructions, as well as other local deployment options including using docker compose and running the bare director binary, are available at https://github.com/sandgardenhq/getting-started/blob/main/local/README.md.

The easiest way to deploy Sandgarden in local develoment mode is to use Dev Container. This provides a complete development environment for Sandgarden workflows:

  • VS Code configured with Python tooling
  • Sandgarden Director running as a sidecar service
  • Your code is mounted in the container as /workspaces/sandgarden

Setup​

  1. Copy the environment file and add your API key:

    cp .devcontainer/.env.example .devcontainer/.env

  2. Edit .env and replace YOUR_SAND_API_KEY with your actual Sand API key

  3. Open this directory in VS Code and click "Reopen in Container" when prompted

The Director service will be available at http://localhost:8987 and visible in the Sandgarden UI. Your workspace will be mounted and ready for workflow development.

Cloud deployment​

note

The following instructions are also available here: https://github.com/sandgardenhq/getting-started/blob/main/aws/vpc/README.md

This guide demonstrates how to deploy a Sandgarden director pool into your private AWS infrastructure. The deployment:

  • Creates a highly available director pool
  • Configures secure network access
  • Sets up monitoring and logging

Prerequisites​

  • Existing AWS VPC
  • AWS CLI configured with appropriate permissions
  • Terraform or OpenTofu installed locally

Inputs​

Required:

  • namespace - Unique identifier for your deployment (e.g., "sandgarden-poc")
  • vpc_id - ID of your existing VPC where resources will be deployed
  • sand_api_key - Your Sandgarden API key for director authentication

Optional:

  • tags - Map of tags to apply to all resources (default: { app = "sandgarden", role = "director" })
  • aws_region - AWS region for deployment (default: "us-west-2")

Usage​

  1. Copy the example variables file and edit it with your specific values.
cp terraform.tfvars.example terraform.tfvars
namespace = "sandgarden-poc"              # Your unique identifier
vpc_id    = "vpc-1234567890abcdef0"      # Your VPC ID
tags      = {
  app  = "sandgarden"
  role = "director"
}
sand_api_key = "your_api_key_here"

# Network Configuration
public_subnet_cidr  = "10.0.1.0/24"      # Must be within VPC CIDR
private_subnet_cidr = "10.0.2.0/24"      # Must be within VPC CIDR
  1. Initialize Terraform and apply the configuration.
tofu init
tofu apply

Outputs​

  • lambda_role_arn - ARN of the IAM role created for Lambda functions to use
  • ecr_registry_url - URL of the ECR repository where container images are stored

Resources Created​

This Terraform configuration creates the following AWS resources:

Network Resources:

  • Network Load Balancer in public subnets
  • VPC Endpoints for ECR, CloudWatch Logs, and Secrets Manager
  • Security groups for NLB and ECS tasks

Container Resources:

  • ECS EC2 cluster
  • ECS task definition and service
  • ECR repository with pull-through cache
  • CloudWatch log group for container logs

IAM Resources:

  • ECS task execution role
  • ECS task role
  • Lambda execution role

Other:

  • Secrets Manager secret for API key
  • SSM Parameter for ECR repository URL

Installing and configuring the sand CLI​

If you're not in a devcontainer (where sand is natively available), the next step is to download and install the sand CLI. From the Sandgarden dashboard, download the Sandgarden CLI for your platform from the available options and place it somewhere in PATH. The below example will download the correct file for an Apple Silicon system:

curl -o sand -L 'https://app.sandgarden.com/api/assets/sand/latest/sand_osx_arm64' &&\
    chmod +x sand &&
    sudo mv sand /usr/local/bin/sand

In order to run commands via sand, you'll need a Sandgarden API key in the SAND_API_KEY environment variable. A director key will work here, or you can generate an API-only key, either via the CLI or in the UI.

Next steps​

Once your directors are up and reporting to the Sandgarden backend, proceed to Part 2.