Get started with EnvTie.dev

Quick start

1. Create an account and a workspace. A workspace holds your projects, runners, and teammates. You become its owner.
2. Add a project for each application or repository, and set up its blueprint by choosing the integrations it should create.
3. Register a runner under Runners. Copy the token (it's shown once) and the signing key into your CI secrets.
4. Plan an environment by giving it a name, review the signed plan, and approve it. The runner picks it up within seconds.

Blueprints

Each project has one blueprint. It lists the components every environment needs, how their outputs are bound to destinations, and a policy for expiry and protection. Every environment you plan gets its own copy of those resources, so new environments only need a name. In the dashboard, Set up blueprint lets you choose integrations such as Neon, Upstash Redis or Vector, Stripe, Sentry, Mailtrap, Resend, Vercel Hosting or Blob, or a custom adapter. Each selected integration has its own step for provider ids, then you choose whether outputs go to a dotenv file or a GitHub environment. Write YAML is there when you already have a blueprint.

# Canonical Neon + Upstash blueprint for macOS and Linux. EnvTie.dev resolves
# official adapter binaries and verifies their signed-plan SHA-256 metadata.
name: consumer-bench
components:
  - id: postgres
    adapter: neon@1
    ownership: managed
    config:
      project_id: REPLACE_WITH_NEON_PROJECT_ID
      database_name: REPLACE_WITH_NEON_DATABASE
      role_name: REPLACE_WITH_NEON_ROLE
  - id: redis
    adapter: upstash@1
    ownership: managed
    depends_on: [postgres]
    config:
      email: REPLACE_WITH_UPSTASH_EMAIL
      platform: aws
      primary_region: us-east-1
bindings:
  - from: postgres.DATABASE_URL
    to: dotenv.DATABASE_URL
  - from: redis.UPSTASH_REDIS_REST_URL
    to: dotenv.UPSTASH_REDIS_REST_URL
  - from: redis.UPSTASH_REDIS_REST_TOKEN
    to: dotenv.UPSTASH_REDIS_REST_TOKEN
policy:
  expires_in: 1d
  protect: false

• Saving a change creates a new numbered version; saving identical content, or restoring an older version from the history, reuses it. New plans always use the current version.
• Environments built from an older version are marked Update available. Re-planning one keeps its existing resources and creates only the components added since. Removing a component requires destroying the environment first.
• Only workspace owners can change the blueprint. Automate it with PUT /v1/workspaces/{id}/projects/{id}/blueprint if you keep the file in your repository.
• ownership: managed resources are created and destroyed by EnvTie.dev. referenced resources are bound but never changed.
• Official blueprints use logical adapter ids such as neon@1. The signed plan carries the immutable release metadata; the runner downloads only selected adapters and verifies SHA-256 before execution. Custom local adapters still require an executable path and pin.
• Binding destinations: github.environment.secret.*, github.environment.variable.*, github.environment.url, env.*, file.<path>, and dotenv.*. dotenv.* writes .envtie/bindings/<environment>.env in the runner's working directory. The file is relative to the customer runner's working directory.
• A Neon and Upstash blueprint binds DATABASE_URL, UPSTASH_REDIS_REST_URL, and UPSTASH_REDIS_REST_TOKEN. The setup wizard writes those to a per-environment dotenv file, or to GitHub Environment secrets and variables when you also select the GitHub provider. Checked-in copies live in https://github.com/coddicat/envtie-core/tree/main/blueprints/. The CI example binds the same outputs to the per-PR GitHub Environment.
• Run a customer runner with npx @envtie.dev/cli@1.8.0-beta.5 runner execute, the container, or the GitHub Action. No EnvTie.dev source checkout is required.
• database_name and role_name must already exist on the Neon parent branch. Discover those names from the Neon API. Do not invent them.
• Never put credentials in a blueprint. Fields that look like secrets are rejected.

Runners

Runners execute approved plans in your infrastructure and only make outbound HTTPS calls. Each needs ENVTIE_API_URL, ENVTIE_RUNNER_TOKEN, and ENVTIE_PUBLIC_KEY, plus the provider keys its adapters declare. Keep the token in the process environment or a secret store, not on the command line. Before a Neon and Upstash apply, the open-source envtie-core preflight scripts check tools, credential presence, control-plane health, Neon project access, and the Upstash database list. They print status codes only and skip a provider call when that input is still missing.

GitHub Actions

The action downloads and verifies the CLI. Start the workflow by hand from the Actions tab. Signed plans then install only the selected adapters and run the waiting jobs.

# Start this workflow by hand from the Actions tab.
on:
  workflow_dispatch:
concurrency: envtie-runner
jobs:
  run:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: coddicat/[email protected]
        with:
          api-url: https://your-envtie-host
          runner-token: ${{ secrets.ENVTIE_RUNNER_TOKEN }}
          public-key: <shown in the dashboard>
        env:
          NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
          MAILTRAP_API_TOKEN: ${{ secrets.MAILTRAP_API_TOKEN }}
          RESEND_API_KEY: ${{ secrets.RESEND_API_KEY }}
          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
          STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}
          UPSTASH_API_KEY: ${{ secrets.UPSTASH_API_KEY }}
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}

Pull-request previews

Configure the GitHub provider in the Blueprint wizard and name the repository there. Under workspace Integrations, create one private GitHub App for the workspace, install it, and store its id, private key, project API key, and provider credentials as Actions secrets. EnvTie stores only nonsecret App metadata. The committed workflow runs on pull requests. Closing a pull request destroys that environment, and a manual run executes envtie preview sweep --run to destroy expired environments. The GitHub adapter creates the stable id pr-<number>; the dashboard shows it as PR #<number> · <title> when the workflow reports the pull request. The same job writes secrets into that environment. Fork pull requests are skipped.

For other CI systems, a project owner can create a scoped CI token and run the CLI to apply pr-<number> on pull-request open or update and destroy it on close or merge. envtie preview sweep --run destroys unprotected environments in that prefix whose expiry has passed. The token cannot operate outside its prefix or destroy protected environments. Keep provider credentials and the runner token as separate repository secrets, disable cancellation during provider mutations, and use a short blueprint expiry as a cleanup backstop.

Docker

# Same pin as the Action and CLI (ENVTIE_RUNNER_VERSION / RUNNER_VERSION).
docker run -d --name envtie-runner --restart unless-stopped \
  -e ENVTIE_API_URL -e ENVTIE_RUNNER_TOKEN -e ENVTIE_PUBLIC_KEY \
  -e NEON_API_KEY -e MAILTRAP_API_TOKEN -e RESEND_API_KEY -e SENTRY_AUTH_TOKEN -e STRIPE_SECRET_KEY -e UPSTASH_API_KEY -e VERCEL_TOKEN \
  ghcr.io/coddicat/envtie-runner:1.8.0-beta.5

CLI

# The CLI prompts for the API URL, public key, and runner token.
npx --yes "@envtie.dev/[email protected]" runner execute

Adapters

Official adapters live in the catalog as logical ids such as neon@1. The signed plan carries immutable release metadata; the runner downloads only the adapters a plan uses and verifies SHA-256 before execution. Dual-product adapters use a product field: Upstash is redis or vector; Vercel is hosting or blob.

Custom adapters

An adapter is any executable that reads one JSON request on stdin and writes one JSON response on stdout, with hooks manifest, read, apply, validate, outputs, and destroy. The Go SDK in sdk/adapter handles the protocol.

1. With the Go toolchain installed, run npx @envtie.dev/cli@1.8.0-beta.5 adapter init <name>.
2. Edit the scaffold, then run envtie adapter build to refresh the binary and SHA-256 pin.
3. In the Blueprint wizard choose Custom adapter (or Write YAML) and set adapter, executable, and sha256.
4. Put provider tokens on the runner—never in the blueprint.

Official providers use the catalog path above and do not need a local binary pin.

Provider credentials

Credentials never belong in the blueprint. Put them on the runner process or as repository Actions secrets, and reference each name under the workflow env block. A secret that exists in GitHub but is not listed under env is invisible to the runner.

• NEON_API_KEY, UPSTASH_API_KEY, STRIPE_SECRET_KEY (prefer sk_test_…), MAILTRAP_API_TOKEN, RESEND_API_KEY, VERCEL_TOKEN, SENTRY_AUTH_TOKEN (org auth token with project:admin).
• Preview workflow: wire those secrets in .github/workflows/envtie-preview.yml. Runner workflow: the same names in envtie-runner.yml.
• Local CLI: export the keys, then run npx @envtie.dev/cli@1.8.0-beta.5 runner execute. When a plan uses GitHub, enter the path to the App private key .pem (GitHub App → Credentials → Key pairs), or set ENVTIE_GITHUB_APP_PRIVATE_KEY_FILE. GitHub shows that key once; generate a new key if you lost the file.
• If destroy leaves an environment in Residual, confirm credentials and retry destroy. The Residuals list shows which managed components remain.

Teams and roles

Invite teammates by email under Members. Invitations are accepted automatically when that verified address signs in.

• Owners approve plans, destroy environments, manage runners, members, and billing.
• Members view inventory and create plans for owners to approve.

Every workspace keeps at least one owner. The Activity page records who approved, changed, or removed what.

Slack notifications

Under Integrations → Slack, owners paste a Slack Incoming Webhook URL. EnvTie posts environment lifecycle updates (plan, approve, ready, failed, destroy, expiry) to that channel. Messages never include provider secrets. You can limit alerts to one project, pause delivery, or send a test message.

Tiers and billing

Subscription tiers limit active environments, runners, and members per workspace. Owners upgrade, switch tiers, and manage invoices from Billing. See pricing for the limits of each tier. Provider resources (Neon, Upstash, Vercel, Stripe, and others) are billed separately by those providers; EnvTie limits count EnvTie environments only.

Self-hosting

EnvTie Core is open source under Apache-2.0 and contains the CLI, runner, adapters, SDK, blueprint contracts, and GitHub Action. The hosted control plane and dashboard are operated separately. Contact [email protected] about hosted-control-plane deployment.