Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.specific.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Dev commands

The dev block on a service lets you override the production command for local development. This is where you use hot-reload servers, watch modes, or any command optimized for a fast feedback loop. 
service "web" {
  build = build.web

  command = "node server.js"

  dev {
    command = "npm run dev"
  }

  endpoint {
    public = true
  }

  env = {
    PORT = port
  }
}
When specific dev runs, it uses npm run dev instead of node server.js. During deployment, the production command is used.

​
Dev-only services

A service with a dev.command but no top-level command only runs in local development. It is ignored during deployment. This is useful for running local infrastructure like a mock API. 
service "mock-api" {
  dev {
    command = "npx json-server --watch db.json --port $PORT"
  }

  endpoint {
    public = true
  }

  env = {
    PORT = port
  }
}

​
Dev environment variable overrides

The dev.env block lets you override environment variables for local development. Variables defined in dev.env take precedence over the top-level env block when running locally. 
service "worker" {
  build = build.worker

  command = "node worker.js"

  dev {
    command = "npx tsx watch worker.ts"
    env = {
      TEMPORAL_ADDRESS = "localhost:7233"
      TEMPORAL_NAMESPACE = "default"
    }
  }

  env = {
    TEMPORAL_ADDRESS = config.temporal_address
    TEMPORAL_NAMESPACE = config.temporal_namespace
    TEMPORAL_API_KEY  = secret.temporal_api_key
  }
}
In this example, the worker connects to a local Temporal server during development and to Temporal Cloud in production.

​
Port allocation

Specific automatically allocates stable ports for each service. Ports are consistent across restarts — the same service always gets the same port for a given project and instance key. Ports are injected through environment variables:
  • port — the port for the default endpoint
  • endpoint.<name>.port — the port for a named endpoint
service "api" {
  build = build.api

  command = "node server.js"

  endpoint "http" {
    public = true
  }

  endpoint "grpc" {}

  env = {
    HTTP_PORT = endpoint.http.port
    GRPC_PORT = endpoint.grpc.port
  }
}

​
Service logs

While specific dev is running, each service’s stdout and stderr are written to a per-service log file: 
.specific/keys/<key>/logs/<service>.log
Without --key, the path is .specific/keys/default/logs/<service>.log. Each line is prefixed with an ISO-8601 timestamp and the stream it came from: 
[2026-05-06T14:23:11.482Z] [stdout] Listening on port 3000
[2026-05-06T14:23:11.500Z] [stderr] warning: deprecated API
This makes the logs easy for a coding agent to read or grep when debugging a service, instead of having to watch the live specific dev output. For example: 
tail -f .specific/keys/default/logs/api.log
grep -i error .specific/keys/default/logs/api.log
Each file is capped at 1 MB. When a service produces enough output to exceed that, the file is truncated to the most recent ~512 KB on a line boundary, so the path is stable and always contains the latest logs.

​
Multi-instance support

Run isolated development environments side-by-side with the --key option. Each instance gets its own data, ports, and URLs. 
specific dev --key feature-auth
With a key, service URLs become: 
https://<service>.<key>.spcf.localhost
For example, https://web.feature-auth.spcf.localhost. Each instance stores its data separately under .specific/keys/<key>/, so databases and other state are fully isolated. Automatic git worktree detection: When working in a git worktree, Specific automatically detects the worktree name and uses it as the instance key. No --key flag needed.

​
Tunnel mode

Expose your local services to the internet with --tunnel. This gives each public service a publicly accessible URL — useful for sharing work with others, testing webhooks, or developing on machines where local DNS setup is not possible. 
specific dev --tunnel
Services are available at: 
https://<subdomain>.tunnel.spcf.app
Tunnel mode skips local TLS certificate and DNS setup entirely, so it works without any system configuration or password prompts.