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 build block 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.

Choose an AWS profile or account¶

A Caution user can have BYOC apps in different AWS accounts. Run setup from each app's directory with the credentials for that app's target account.

To select a named AWS profile, set AWS_PROFILE for the command and pass the target region explicitly:

AWS_PROFILE=production caution init --byoc --region us-east-1

The CLI reads static credentials (including an optional session token) for that profile from ~/.aws/credentials and reads its default region from ~/.aws/config. Profiles that depend on AWS SSO, credential_process, or an assumed role are not resolved directly; expose their resolved temporary credentials through the standard AWS environment variables instead:

export AWS_ACCESS_KEY_ID=your-temporary-access-key
export AWS_SECRET_ACCESS_KEY=your-temporary-secret-key
export AWS_SESSION_TOKEN=your-temporary-session-token # if required
export AWS_REGION=us-east-1
caution init --byoc

AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY take precedence over AWS_PROFILE. Unset them before selecting a named profile if they point to a different account. If the AWS CLI is installed, confirm the selected account before provisioning:

AWS_PROFILE=production aws sts get-caller-identity

Use credentials for the same AWS account when you later run caution teardown --byoc.

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:

Each normal caution init --byoc setup generates a new deployment ID and a dedicated bucket. Subsequent deployments of that app reuse its bucket; the bucket is not shared with other BYOC apps in the same Caution user or AWS account. caution teardown --byoc empties and deletes the bucket along with the app's other BYOC resources.

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 reference secrets with env::vault in your caution.hcl.

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 --save-pcrs

The --save-pcrs flag saves the verified PCR values to .caution/trusted_hashes.json. This file is required before sending locksmith shards — commit it alongside your other .caution/ files.

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: