Docs

Services.

A Service is one deployable unit. It runs inside a Project, which lives inside a Team. Each Service has a type, a lifecycle state, and a fieldwick.json config file that tells the platform how to build, run, and scale it.

Service types

Pick the type that matches what you are deploying. The platform routes traffic, manages lifecycle, and sets scaling defaults differently for each one.

web - An HTTP server that receives public traffic. Gets a stable hostname and TLS automatically. Scales up by replica count.
worker - A long-running background process with no inbound traffic. Used for queue consumers, AI pipelines, and event processors.
cron - A process that runs on a schedule you define (standard cron syntax). Exits after each run. Useful for nightly jobs, cleanup tasks, and timed reports.
static_site - A folder of pre-built HTML, CSS, and JS files served from the edge. No server process runs. Build output is uploaded at deploy time.
postgres - A managed PostgreSQL database. Connection string is injected as an environment variable into sibling Services automatically.
redis - A managed Redis instance for caching and pub/sub. Available inside the Project network only unless you explicitly expose it.
mysql - A managed MySQL database, same injection model as postgres.
mongodb - A managed MongoDB instance with connection URI injection.
volume - A persistent filesystem volume that can be mounted into any other Service in the same Project. Survives redeploys and restarts.

Lifecycle states

Every Service moves through these states. You can see the current state in the dashboard or via fieldwick services list.

building - The platform is running your build command and creating a container image. No traffic is served yet.
deploying - The new image is being rolled out. Health checks run. Old replicas stay up until the new ones pass.
active - The Service is running and healthy. Traffic routes to it normally.
suspended - Replicas are scaled to zero. No compute charges accrue. Unsuspend via the dashboard or CLI to bring it back.
failed - The last build or deploy attempt did not succeed. The previous active version (if any) keeps serving. Check the deploy log for the error.

fieldwick.json

Place a fieldwick.json file at the root of your repository (or the directory you deploy from). It controls how the platform builds your code, starts the process, performs health checks, and scales replicas. All fields are optional - the platform applies sensible defaults when a field is absent.

{
  "build": {
    "command": "pnpm run build",
    "dockerfilePath": null
  },
  "start": {
    "command": "node dist/server.js",
    "port": 3000
  },
  "healthcheck": {
    "path": "/health",
    "intervalSeconds": 15,
    "timeoutSeconds": 5,
    "failureThreshold": 3
  },
  "scaling": {
    "minReplicas": 1,
    "maxReplicas": 4
  }
}

Setting minReplicas: 0 enables scale-to-zero. The Service suspends when idle and wakes on the next inbound request. Use this for staging environments and low-traffic internal tools to avoid idle compute costs.

Creating and managing Services

Use the CLI or the dashboard. Every Service belongs to a Project. Pass --project with the Project ID shown in the dashboard URL or in fieldwick projects list.

# Create a new web service backed by a GitHub repo
fieldwick services create \
  --name api \
  --project <project-id> \
  --source-type github \
  --source-ref owner/repo

# List all services in the current project
fieldwick services list

# Suspend a service (scales to zero, stops billing compute)
fieldwick services suspend <service-id>

After creating a Service, the first deploy starts automatically. Subsequent deploys trigger on every push to the source branch unless you set deploy hooks to manual in fieldwick.json.

Soft-delete and restore

Deleting a Service is non-destructive for 7 days. The Service is immediately removed from routing and the dashboard, but its configuration, environment variables, and deploy history are retained on the backend. Run the restore command any time within that window to bring it back exactly as it was.

# Delete a service (soft - recoverable for 7 days)
fieldwick services delete <service-id>

# Restore within the 7-day window
fieldwick services restore <service-id>

After 7 days the Service is permanently purged along with its deploy artifacts, logs, and environment variables. If you need longer retention, export your environment variables first via the environment variables page.

Where Services fit

Services live inside Projects, and Projects live inside Teams. A Team is the billing and access boundary - all members of a Team can see every Project and every Service in that Team. Use separate Teams for separate customers or separate billing entities. Use separate Projects inside one Team to group Services that share environment variables and a private network with each other.

Team
  Project (shared private network + env vars)
    Service: api      (type: web)
    Service: worker   (type: worker)
    Service: db       (type: postgres)
    Service: cache    (type: redis)