Services

Create, inspect, update, and delete services. Manage ingress rules and open interactive shells.

A service is a workload or managed resource running inside an environment. The CLI can create these service types:

Type	Description
`docker`	Any Docker image. Configure image and tag at creation time.
`postgres`	A managed PostgreSQL database.
`redis`	A managed Redis instance.

The service command can be shortened to svc:

edge svc list

All service commands require a workspace, project, and environment.

list

List all services in the active environment.

edge service list
edge service list --json

Example output

SLUG     NAME      TYPE      STATUS
api      API       docker    running
db       Database  postgres  running
cache    Cache     redis     running

create

Create a new service.

edge service create --name <name> --type <type> [flags]

Required flags

Flag	Description
`--name`	Service name
`--type`	Service type: `docker`, `postgres`, or `redis`

Optional flags

Flag	Description
`--image`	Docker image name (e.g. `nginx`)
`--tag`	Docker image tag (e.g. `latest`, `1.25`)
`--storage`	Storage size in GB for Postgres and Redis
`--mode`	Deployment mode for managed data services
`--replicas`	Replica count for Redis where supported
`--readiness-path`	Docker HTTP readiness path, such as `/ready`
`--readiness-port`	Docker container port used by readiness
`--readiness-initial-delay`	Seconds before the first readiness probe (default `0`)
`--readiness-period`	Seconds between probes (default `10`)
`--readiness-timeout`	Probe timeout in seconds (default `1`)
`--readiness-failure-threshold`	Failures before the pod becomes unready (default `3`)
`--readiness-success-threshold`	Successes before the pod becomes ready (default `1`)

Examples

# Docker service
edge service create \
  --name api \
  --type docker \
  --image my-org/api \
  --tag v2.1.0 \
  --readiness-path /ready \
  --readiness-port 8080

The readiness probe is persisted with the Docker service and enables native rolling deployments from its first deployment. If it is omitted, deployments use Recreate.

# Managed Postgres
edge service create --name db --type postgres --storage 20 --mode standalone

# Managed Redis
edge service create --name cache --type redis --storage 10 --mode standalone

get

Get detailed information about a specific service.

edge service get <slug>
edge service get api --json

Example output

FIELD         VALUE
Slug          api
Name          API
Type          docker
Image         my-org/api
Tag           v2.1.0
vCPUs         2
Memory (MB)   512
Replicas      3
Region        ng-west-1
Status        running

update

Update one attribute of a service's configuration. Exactly one flag must be provided per call.

edge service update <slug> [flags]

Flags

Flag	Description
`--name`	New service name
`--vcpus`	New vCPU count
`--replicas`	Docker service replica count, 1–10
`--memory`	New memory in MB
`--image`	New Docker image, optionally including a tag (e.g. `nginx:1.27`, `registry.example.com/app:v2`)
`--readiness-path`	HTTP readiness path, such as `/ready`
`--readiness-port`	Container port used by the readiness probe
`--readiness-initial-delay`	Seconds before the first probe (default `0`)
`--readiness-period`	Seconds between probes (default `10`)
`--readiness-timeout`	Probe timeout in seconds (default `1`)
`--readiness-failure-threshold`	Failures before the pod becomes unready (default `3`)
`--readiness-success-threshold`	Successes before the pod becomes ready (default `1`)
`--delete-readiness-probe`	Remove readiness; subsequent deployments use Recreate

Only one logical update may be performed at a time. Readiness configuration uses --readiness-path and --readiness-port together and may include its tuning flags.

Changes to resources, images, and readiness probes are staged in the service's changeset and take effect on the next deployment. Use edge service changeset to review and act on pending changes.

Examples

# Rename a service
edge service update api --name api-v2

# Scale memory (staged — deploy to apply)
edge service update api --memory 1024

# Change vCPU allocation (staged — deploy to apply)
edge service update api --vcpus 4

# Scale a Docker service (staged — deploy to apply)
# Rolling deployments also require a configured readiness check
edge service update api --replicas 2

# Configure readiness and enable native rolling deployments
edge service update api --readiness-path /ready --readiness-port 8080

# Remove readiness; subsequent deployments use Recreate with expected downtime
edge service update api --delete-readiness-probe

# Change the Docker image and tag (staged — deploy to apply)
edge service update api --image my-org/api:v3.0.0

# Switch to a fully-qualified registry image
edge service update worker --image ghcr.io/my-org/worker:sha-abc1234

changeset

View the pending changes for a service and choose whether to deploy or discard them.

Changes made with edge service update --vcpus, --replicas, --memory, or --image, as well as variable mutations (edge variables set), are staged in a changeset rather than applied immediately. The changeset accumulates changes until you either deploy the service (which applies and clears it) or explicitly discard it.

edge service changeset <svc-slug>

Flags

Flag	Short	Description
`--yes`	`-y`	Auto-approve: deploy immediately without prompting
`--json`		Print the raw changeset array to stdout instead of the interactive table

What it does

Fetches the service and displays all staged changes as a table.
Then, depending on the mode:

Mode	Behaviour
`--yes` / `-y`	Deploys immediately — no prompt.
Interactive (no `--yes`)	Prompts for an action (see table below).
Non-interactive, no `--yes`	Prints the table and exits — the changeset is unchanged.

Interactive prompt choices:

Choice	Key	Effect
Approve	`a`	Deploys the service — all staged changes are applied and the changeset is cleared.
Discard	`d`	Rolls back all staged changes to their previous values and clears the changeset.
Exit	`e`	Does nothing. The changeset remains as-is.

Examples

# Interactive — prompts for approve / discard / exit
edge service changeset api

# Auto-approve and deploy without prompting
edge service changeset api --yes
edge service changeset api -y

Pending changes for service api:

TYPE          ACTION  NAME          FROM                  TO
docker_image  update  docker_image  my-org/api:v2.1.0     my-org/api:v3.0.0
memory        update  memory        512                   1024

What would you like to do?
  [a] approve — deploy the service with these changes
  [d] discard — roll back all pending changes
  [e] exit    — do nothing

Choice [a/d/e]: a
✓ Deployment started (slug: dep-01j2k3..., status: pending)

JSON output

edge service changeset api --json

Prints the raw changeset array to stdout:

[
  {
    "type": "docker_image",
    "action": "update",
    "name": "docker_image",
    "previous_value": "my-org/api:v2.1.0",
    "new_value": "my-org/api:v3.0.0"
  },
  {
    "type": "memory",
    "action": "update",
    "name": "memory",
    "previous_value": "512",
    "new_value": "1024"
  }
]

edge deploy up checks for a pending changeset before deploying. In interactive mode it prompts for confirmation; pass --yes / -y to skip the prompt (e.g. in CI). You don't need to run edge service changeset separately unless you want to review or discard changes without deploying.

delete

Delete a service. Prompts for confirmation unless --force is passed.

edge service delete <slug>
edge service delete api --force

Flags

Flag	Description
`--force`	Skip the confirmation prompt

Deleting a service is permanent. All deployments, variables, and ingress rules for that service are also removed.

ingress

Manage ingress rules for a service. HTTP and gRPC ingress expose a service port through an auto-assigned FQDN or custom domain. TCP and UDP ingress expose a public port directly.

ingress add

edge service ingress add <svc-slug> --protocol <protocol> --port <port> [--custom-fqdn <domain>]

Flag	Description
`--protocol`	`http`, `grpc`, `tcp`, or `udp` (required)
`--port`	Container port to expose (required)
`--custom-fqdn`	Custom domain name for HTTP/gRPC ingress only

# Expose port 8080 over HTTP
edge service ingress add api --protocol http --port 8080

# Use a custom domain
edge service ingress add api --protocol http --port 8080 --custom-fqdn api.acme.com

# Expose a TCP port
edge service ingress add db --protocol tcp --port 5432

# Expose a UDP port
edge service ingress add game --protocol udp --port 7777

TCP and UDP ingress rules do not use FQDNs. Do not pass --custom-fqdn with tcp or udp.

ingress delete

edge service ingress delete <svc-slug> <ingress-slug>

edge service ingress delete api ingress-01j2k3...

shell

Open an interactive terminal session inside a running service container.

edge service shell <svc-slug>

The CLI opens a shell session, streams your terminal input/output in real time, and resizes the terminal automatically when you resize your window.

Requirements

The service must be in running status. If it is stopped or still deploying, the connection will be refused.
Works with docker services only. Managed databases (postgres, redis) do not expose a shell endpoint.

Example

# Open a shell in the "api" service
edge service shell api

# Combine with global flags to target a specific environment
edge service shell api -w my-workspace -p my-project -e staging

Once connected, you have a full interactive shell inside the container. Press Ctrl+D or type exit to end the session.

The shell tries /bin/bash first, then falls back to /bin/sh.

Shell sessions connect to a single running replica. In multi-replica deployments, there is no guarantee which replica you land on.

config

Mount static config files (e.g. Caddyfile, nginx.conf) into a service at deploy time — without building a custom Docker image.

See the Configs reference for the full command documentation, including variable interpolation and a complete Caddy example.

Services

On this page