Deployment And Auth

Purpose and Scope

This page explains how Flue treats deployment and runtime authentication on AWS as part of the agent harness, not as an afterthought outside the application. The AWS guide is written around the Node target, which is a long-running HTTP server rather than a serverless function. That distinction matters because Flue agents keep sessions in process and serve streamed responses over long-lived connections. The deployment platform therefore needs to keep a containerized server running, route traffic to it, and provide the runtime secrets it needs when it starts.

Sources: apps/docs/src/content/docs/ecosystem/deploy/aws.md

The practical model is a clean split of responsibility. Flue owns the server process, the HTTP runtime, agent sessions, and streaming behavior. AWS owns the surrounding platform: container registry, compute service, load balancing, health checks, security groups, scaling, IAM roles, and secret injection. Thinking about deployment this way helps teams avoid two common mistakes: packaging secrets into the image, or choosing an execution environment that is optimized for short function invocations rather than durable, streamed agent work.

Sources: apps/docs/src/content/docs/ecosystem/deploy/aws.md

Relevant Source Files

• apps/docs/src/content/docs/ecosystem/deploy/aws.md — The first-party AWS deployment guide. It defines the Node target deployment assumption, the shared Docker image flow through Amazon ECR, the required port and health-check alignment, the environment and secret boundary, and the supported AWS compute options including ECS Express Mode.

Core Deployment Primitive

The core primitive for AWS is a Docker image that contains the built Flue Node server. Every AWS option in the guide starts from the same image: build it locally or in CI, tag it for a private Amazon ECR repository, authenticate Docker to ECR, push the image, and then point an AWS compute service at that immutable artifact. This makes the deployment target interchangeable while keeping the application artifact constant. ECS Express Mode, EC2, and ECS on Fargate are deployment choices around the same server image, not different Flue application modes.

Sources: apps/docs/src/content/docs/ecosystem/deploy/aws.md

The server binds the port supplied by the runtime environment. The Docker deployment guide uses port 8080, and the AWS guide emphasizes that whatever port you choose must be matched by the platform configuration and health check. This is a small setting with large operational consequences: a container can be healthy internally while the load balancer marks it unhealthy if the exposed port or health-check path does not match. For Flue, that health-check alignment protects long-running sessions by ensuring traffic only reaches tasks that are actually serving.

Sources: apps/docs/src/content/docs/ecosystem/deploy/aws.md

aws ecr create-repository --repository-name flue-agents
docker build -t flue-agents .
docker tag flue-agents:latest <account>.dkr.ecr.<region>.amazonaws.com/flue-agents:latest
aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <account>.dkr.ecr.<region>.amazonaws.com
docker push <account>.dkr.ecr.<region>.amazonaws.com/flue-agents:latest

Runtime Auth and Secret Boundary

In this guide, auth is not limited to user login. It includes the credentials that let the agent harness call model providers, connect to durable state, and let AWS services pull and run the container. The built server reads only the environment supplied when the process starts; it does not load a local environment file in AWS. That means provider keys, the optional model selector, and the database connection string are deployment inputs. They belong in the platform secret store, never in the Docker image.

Sources: apps/docs/src/content/docs/ecosystem/deploy/aws.md

The guide names provider keys such as Anthropic and OpenAI credentials, an optional model specifier, and the database URL as runtime environment concerns. Plain environment variables can be used for non-sensitive values, but sensitive values should be resolved from AWS Secrets Manager or SSM Parameter Store through the task secret mechanism. This keeps the image reusable across environments and prevents accidental credential disclosure through image layers, registries, build logs, or local developer machines. It also lets operators rotate credentials independently from application builds.

Sources: apps/docs/src/content/docs/ecosystem/deploy/aws.md

{
  "environment": [{ "name": "MODEL_SPECIFIER", "value": "anthropic/claude-sonnet-4-6" }],
  "secrets": [
    { "name": "DATABASE_URL", "valueFrom": "arn:aws:secretsmanager:<region>:<account>:secret:flue/database-url" }
  ]
}

AWS Compute Options

ECS Express Mode is the recommended path because it asks AWS to provision the surrounding stack from one service command. The guide describes it as taking a container image and two IAM roles, then creating an ECS service on Fargate, an Application Load Balancer with health checks, CPU-based auto scaling, security groups, and a service URL. This is the most managed option in the AWS guide: teams still pay for the underlying resources, but they do not have to manually assemble every infrastructure component before exposing the Flue server.

Sources: apps/docs/src/content/docs/ecosystem/deploy/aws.md

The two IAM roles in the Express Mode example clarify the auth boundary between container execution and infrastructure provisioning. The execution role is responsible for operations such as pulling the private ECR image and resolving task secrets. The infrastructure role gives the managed ECS Express workflow authority to create and operate the surrounding resources. Keeping those roles explicit helps teams audit what AWS is allowed to do on behalf of the service and what the running task itself can access at runtime.

Sources: apps/docs/src/content/docs/ecosystem/deploy/aws.md

aws ecs create-express-gateway-service
--service-name flue-agents
--execution-role-arn arn:aws:iam::<account>:role/ecsTaskExecutionRole
--infrastructure-role-arn arn:aws:iam::<account>:role/ecsInfrastructureRoleForExpressServices
--primary-container '{ "image": "<account>.dkr.ecr.<region>.amazonaws.com/flue-agents:latest", "containerPort": 8080 }'
--health-check-path /health
--scaling-target '{"minTaskCount":1,"maxTaskCount":4}'
--monitor-resources

System-to-Code Mapping

The source document maps directly to an operational sequence. First, produce the shared Docker image for the Flue Node server. Second, push that image to a private ECR repository. Third, choose the AWS compute layer that will keep the HTTP server running. Fourth, configure port and health-check settings so the platform can safely route traffic. Fifth, inject runtime environment values and secrets at process start. These steps are ordered because each depends on the previous artifact or platform boundary being correct.

Sources: apps/docs/src/content/docs/ecosystem/deploy/aws.md

Operational Checks and Next Steps

Before deploying a production agent, verify the assumptions that affect durable work. Confirm that the service is not configured as a short-lived function, that the minimum task count keeps at least one server available, that the health-check path is accepted by the load balancer, and that the container port matches the port the server binds. Then confirm that model credentials and database connectivity are present only as runtime configuration. These checks are especially important because Flue sessions and streamed responses depend on a stable, reachable process.

Sources: apps/docs/src/content/docs/ecosystem/deploy/aws.md

After this page, read the Docker deployment guide to understand the image build in more detail, then read the Node target material to understand the runtime server that AWS is hosting. If you are choosing persistence, pair the AWS deployment guide with the database adapter pages because the database URL is one of the required runtime secrets. If you need provider-specific model behavior, review the model and provider references before setting the model specifier in your AWS service configuration.