caution.hcl reference¶

Configure how your application runs on Caution.

Overview¶

caution.hcl is the HCL configuration file that tells Caution how to build, run, and verify your application. Place it in the root of your repository. caution init generates a template for you.

When both caution.hcl and a Procfile are present, Caution uses caution.hcl. To convert an existing Procfile, run caution apps migrate-procfile.

enclave "main" {
  build {
    app_sources = ["https://codeberg.org/myorg/myapp"]
  }

  network {
    ingress {
      cidr_ipv4 = "0.0.0.0/0"
      port      = 8080
    }
    http {
      domain = "your-domain.xyz"
      port   = 8080
    }
  }

  unit "default" {
    command = "/app/server"
  }
}

Structure¶

A config file has an optional top-level caution { } block for account- and provider-level settings, and exactly one enclave "<name>" { } block describing the workload.

caution {
  # account / provider settings
}

enclave "main" {
  build     { }   # what to build
  resources { }   # cpu / memory
  network   { }   # ingress, egress, http
  debug     { }   # debug + ssh access
  unit "default" { }   # the command to run
}

Fields¶

unit — the command to run¶

The unit "default" block is required. Caution runs the command from the unit named default; a unit with any other name is ignored for startup.

unit "default" {
  command = "/app/server"
  args    = ["--port", "8080"]
  env = {
    LOG_LEVEL = "info"
  }
}

build — container input¶

build {
  containerfile = "deploy/Containerfile"
  app_sources   = ["https://codeberg.org/myorg/myapp"]
  cache         = true
}

resources — cpu and memory¶

resources {
  cpu       = 2
  memory_mb = 512
}

network — ports, traffic, and TLS¶

The network block holds ingress/egress traffic rules and an optional http block for TLS termination. Repeat ingress/egress blocks to add more rules.

network {
  ingress {
    cidr_ipv4   = "0.0.0.0/0"
    port        = 8080
    ip_protocol = "tcp"
  }
  ingress {
    cidr_ipv4  = "0.0.0.0/0"
    start_port = 40000
    end_port   = 40005
  }
  egress {
    cidr_ipv4 = "0.0.0.0/0"
  }

  http {
    domain = "api.example.com"
    port   = 8080
  }
}

ingress / egress¶

Do not declare ports in the reserved 49500-49600 range (see Reserved ports).

http¶

The http block fronts one port with TLS on port 443. By default TLS terminates on the host; with Attested TLS, it terminates inside the enclave.

Encryption modes¶

Add an e2e_encryption block inside http to select STEVE end-to-end encryption or Attested TLS.

STEVE uses an attestation-aware client and provides application-layer encryption:

http {
  domain = "secure.example.com"
  port   = 8080
  e2e_encryption {
    mode         = "steve"
    key_exchange = "x25519"
    cors_origins = ["https://app.example.com"]
  }
}

key_exchange, cors_origins, and allow_plaintext_fallback are STEVE-specific and should be used with mode = "steve". The client must pin the matching key-exchange identifier; STEVE does not negotiate or fall back to another suite. Changing the suite requires a new deployment and changes the measured enclave configuration.

See Use STEVE clients for browser, CLI, Rust, and Swift integration, including pinned PCRs, upgrade allowlists, and TOFU.

STEVE is fail-closed by default. When allow_plaintext_fallback is omitted or false, an ordinary application request that does not use E2P is rejected with 403 {"error":"e2e_required"} and Cache-Control: no-store without contacting the application.

Set allow_plaintext_fallback = true only while migrating legacy clients that cannot yet use STEVE. It restores ordinary plaintext forwarding through STEVE and therefore removes the end-to-end encryption guarantee for those requests. Remove the option after migration.

Attested TLS works with ordinary HTTPS clients and terminates TLS inside the enclave:

http {
  domain = "secure.example.com"
  port   = 8080
  e2e_encryption {
    mode = "tls"
  }
}

Attested TLS requires egress for certificate issuance and periodic external verification of the attested certificate fingerprint. See Deployment configuration for the complete security procedure.

For a gRPC application, set the upstream protocol to h2c (cleartext HTTP/2). Client connections still use TLS; only the enclave-local connection from Caddy to the application is cleartext:

http {
  domain            = "grpc.example.com"
  port              = 50051
  upstream_protocol = "h2c"
  e2e_encryption {
    mode = "tls"
  }
}

Secrets¶

Reference a secret managed by Locksmith with env::vault(...) in a unit's env map. Using env::vault anywhere automatically enables Locksmith for the deployment — there is no separate flag.

unit "default" {
  command = "/app/server"
  env = {
    API_KEY = env::vault("API_KEY")
  }
}

Before deploying, generate a quorum, run caution secret encrypt to write encrypted .caution/secrets/*.asc files, and add the bundle and secrets to your Containerfile:

ADD .caution/quorum-bundle.json /etc/caution/bundle.json
ADD .caution/secrets/ /etc/caution/secrets/

After deploying, send shards with caution secret send-shard from the host-toolchain CLI build, which is the default make install-cli (also make install-cli-host). See Key services for the full setup flow.

debug — console and SSH access¶

debug {
  enabled  = true
  ssh_keys = ["ssh-ed25519 AAAA... user@host"]
}

caution / provider — account and BYOC¶

The top-level caution { } block holds account-level settings and an optional provider block for bring-your-own-compute deployments.

caution {
  provider {
    type   = "aws"
    region = "us-east-1"
  }
}

Reserved ports¶

The reserved app-facing range is 49500-49600. User apps must not declare ports in that range in ingress, egress, http, or application startup commands. Choose the port your app already uses, as long as it is outside the reserved range.

Current reserved/internal service ports:

The public attestation endpoint is the deployment's app URL plus /attestation; do not add :49502 unless your operator explicitly exposes that internal port.

Examples¶

Use these examples as starting points. Adjust commands, ports, and domains to match your application.

Basic application¶

enclave "main" {
  build {
    app_sources = ["https://codeberg.org/example/api"]
  }
  network {
    ingress {
      cidr_ipv4 = "0.0.0.0/0"
      port      = 8080
    }
    http {
      domain = "api.example.com"
      port   = 8080
    }
  }
  unit "default" {
    command = "/app/server"
  }
}

With a custom Containerfile¶

enclave "main" {
  build {
    containerfile = "deploy/Containerfile"
  }
  unit "default" {
    command = "/app/server"
  }
}

Caution builds this with docker build -f deploy/Containerfile . from the repository root.

With HTTP and TCP ports¶

enclave "main" {
  network {
    ingress {
      cidr_ipv4 = "0.0.0.0/0"
      port      = 8232
    }
    ingress {
      cidr_ipv4 = "0.0.0.0/0"
      port      = 8233
    }
    http {
      domain = "node.example.com"
      port   = 8232
    }
  }
  unit "default" {
    command = "/app/server"
    args    = ["--rpc-port", "8232", "--p2p-port", "8233"]
  }
}

Port 8232 (RPC) is reverse-proxied through Caddy with TLS on port 443. Port 8233 (P2P) gets an ingress rule but is accessed directly as raw TCP.

With end-to-end encryption¶

enclave "main" {
  build {
    app_sources = ["https://codeberg.org/example/secure-app"]
  }
  network {
    ingress {
      cidr_ipv4 = "0.0.0.0/0"
      port      = 3000
    }
    http {
      domain = "secure.example.com"
      port   = 3000
      e2e_encryption {
        mode         = "steve"
        key_exchange = "x25519"
        cors_origins = ["https://app.example.com"]
      }
    }
  }
  unit "default" {
    command = "/app/server"
    args    = ["--port", "3000"]
  }
}

With Locksmith secrets¶

enclave "main" {
  build {
    app_sources = ["https://codeberg.org/example/secret-app"]
  }
  network {
    ingress {
      cidr_ipv4 = "0.0.0.0/0"
      port      = 3000
    }
    http {
      domain = "secrets.example.com"
      port   = 3000
    }
  }
  unit "default" {
    command = "/app/server"
    args    = ["--port", "3000"]
    env = {
      DATABASE_URL = env::vault("DATABASE_URL")
    }
  }
}

env::vault enables Locksmith automatically. See Secrets for the bundle and shard-sending steps.

Custom resources with multiple ports¶

enclave "main" {
  resources {
    cpu       = 4
    memory_mb = 4096
  }
  network {
    ingress {
      cidr_ipv4 = "0.0.0.0/0"
      port      = 3000
    }
    ingress {
      cidr_ipv4 = "0.0.0.0/0"
      port      = 9000
    }
    http {
      domain = "ml.example.com"
      port   = 3000
    }
  }
  unit "default" {
    command = "/app/ml-inference"
  }
}

Port 3000 is reverse-proxied through Caddy; port 9000 is exposed as raw TCP.

Bring your own compute (AWS)¶

caution {
  provider {
    type   = "aws"
    region = "us-east-1"
  }
}

enclave "main" {
  unit "default" {
    command = "/app/server"
  }
}