Deploy in your own AWS account¶

Deploy Caution enclaves in your own AWS infrastructure while Caution handles the standard Docker build and deployment orchestration.

What is bring your own compute?¶

Bring your own compute (BYOC) lets you run confidential enclaves in your own AWS account. A one-time setup script creates isolated AWS infrastructure and a scoped IAM identity that can only interact with resources tagged for Caution, then Caution manages deployments within that environment. For full details, see the bring your own compute reference.

What you need¶

Before you begin, ensure you have the following:

AWS credentials should use a least-privilege IAM role when possible. Admin credentials can be used as an alternative. See bring-your-own-cloud-setup for guidance.

Install the CLI¶

Follow the installation instructions in the CLI README.

Create an account¶

To create an account, you'll need a valid access code and a passkey. You can register in the browser or with the CLI.

If you do not have an access code, request one at info@caution.co.

caution register --alpha-code <your_code>

Add an SSH key¶

Add an SSH key so you can authenticate your Caution deployments:

caution ssh-keys add --from-agent

Select an application¶

Deploy your own containerized application, or start with one of the Caution demo apps. For this guide, use hello-world-enclave:

git clone https://codeberg.org/caution/demo-hello-world-enclave.git
cd demo-hello-world-enclave

For your own app, make sure the container builds from the repository root with the standard Docker form:

docker build -f Containerfile .

If you use another file, set containerfile in the Procfile and replace Containerfile with that path. Caution uses this build shape and does not pass extra build arguments, so public build-time values need to be part of the image inputs. Use Locksmith for secrets.

Set up your AWS environment¶

Choose how you want to provision the AWS environment for bring your own compute deployments. Both paths continue through the Caution CLI for app registration, Git-based deployment, and verification.

In both paths, setup uses your provisioning credentials to create tagged AWS resources and a scoped IAM user, then registers only the scoped deployment credentials with Caution:

flowchart TB
    subgraph Local["Your setup environment"]
        AppDir["Application directory"]
        AwsCreds["AWS provisioning credentials"]
        CliSetup["CLI-guided setup<br/>caution init --byoc"]
        ManualSetup["Manual setup container<br/>bring-your-own-cloud-setup"]
        ConfigFile["credentials.json.gpg<br/>manual path"]
    end

    subgraph Aws["Your AWS account"]
        Resources["Tagged deployment resources<br/>VPC, subnets, IGW, routing, S3, launch template, ASG"]
        InstanceRole["EC2 instance role<br/>read EIF images"]
        BuilderRole["Builder role<br/>publish EIF images"]
        ScopedUser["Scoped IAM user<br/>tag-limited policy"]
    end

    subgraph Caution["Caution"]
        AppRecord["Caution app record"]
        DeploymentCreds["Scoped deployment credentials"]
    end

    AppDir --> CliSetup
    AwsCreds --> CliSetup
    AwsCreds --> ManualSetup

    CliSetup -->|provisions| Resources
    CliSetup -->|creates| InstanceRole
    CliSetup -->|creates| BuilderRole
    CliSetup -->|creates| ScopedUser
    CliSetup -->|registers automatically| AppRecord

    ManualSetup -->|provisions| Resources
    ManualSetup -->|creates| InstanceRole
    ManualSetup -->|creates| BuilderRole
    ManualSetup -->|creates| ScopedUser
    ManualSetup --> ConfigFile
    ConfigFile -->|caution init --byoc --config| AppRecord

    ScopedUser --> DeploymentCreds
    AppRecord --> DeploymentCreds

CLI-guided provisioning (recommended)¶

Use this path if you want Caution to provision AWS infrastructure and register deployment credentials automatically.

From your application directory, run:

caution init --byoc

This command detects your AWS credentials, provisions the required AWS infrastructure, creates your app on Caution, and registers the deployment credentials automatically.

Commit the generated .caution/deployment.json to your repository. The deployment file stores the Caution app resource ID so CLI commands can infer the target app from the repository.

Manual provisioning¶

Use this path if you want more control over the AWS infrastructure setup before registering the deployment configuration with Caution.

From a working directory, run:

git clone https://codeberg.org/caution/bring-your-own-cloud-setup.git
cd bring-your-own-cloud-setup

cp .env.example .env
# Edit .env with your AWS credentials

docker build -t caution-provisioner-setup .

docker run --rm \
  --env-file .env \
  -v "$(pwd)/out:/out" \
  caution-provisioner-setup

This provisions the required AWS infrastructure and writes credentials.json.gpg to the out/ directory.

To use the generated encrypted credentials, return to your application directory and run:

caution init --byoc --config /path/to/credentials.json.gpg

Commit the generated .caution/deployment.json to your repository. The deployment file stores the Caution app resource ID so CLI commands can infer the target app from the repository.

What the setup creates¶

The setup flow creates an isolated environment for running enclaves in your AWS account:

Add environment variables¶

If your application needs environment variables, use Key services before deploying. The guide covers non-encrypted variables for public configuration and encrypted variables for secrets, including how to deploy Keymaker, generate shard-holder OpenPGP keys, create a quorum bundle, encrypt values from .env, and enable Locksmith in your Procfile.

Skip this step if your application does not need environment variables.

Deploy the application¶

From your application directory, push the code to Caution:

git push caution main

Caution builds a reproducible enclave image with the standard Docker build and deploys it into the AWS environment you provisioned.

Verify the deployment¶

From your application directory, run the following command to rebuild the image, compare hashes, and confirm exactly what the enclave is running:

caution verify

Cleanup¶

To tear down a BYOC deployment from the CLI, run:

caution teardown --byoc

Run this from your application directory (or ensure local BYOC state exists in ~/.caution/<app>/bring-your-own-cloud.json) and make sure your AWS credentials are available.

If you need manual cleanup details, see the cleanup instructions in the BYOC repo.

Next steps¶

Your application is now running in a verified enclave in your own AWS account. Here's what to explore next: