Environments

Environments are isolated deployment contexts that let you separate your pipelines, agents, and secrets across lifecycle stages such as development, staging, and production. Each environment maintains its own independent set of resources, so changes in one environment never affect another.

Why use environments?

• Isolation -- Keep experimental pipeline changes out of production.
• Separate secrets -- The same secret name (e.g., API_KEY) can hold different values in each environment.
• Independent fleets -- Agent nodes enroll into a specific environment and only run pipelines assigned to that environment.
• Promotion workflow -- Build and test a pipeline in dev, then promote it to staging and production when ready.

Environment selector

The environment selector is the dropdown in the header bar. Switching it changes the global context for the entire application -- the pipeline list, fleet view, alerts, and all other pages update to show only resources belonging to the selected environment.

Default environment

You can set a default environment so VectorFlow automatically selects it when you log in or switch teams.

User default (per-user): Click the star icon next to any environment in the environment selector dropdown. The starred environment becomes your personal default for that team. Click the star again to clear it.

Admin default (per-team): Team admins can set a team-wide default environment from Settings > Team. This applies to all team members who have not set their own personal default.

The fallback chain when loading the app is:

1. User default -- your personally starred environment (if set)
2. Admin team default -- the team-level default environment (if configured by an admin)
3. First in list -- the first environment alphabetically

Creating an environment

Environment detail page

Click any environment name in the list to open its detail page. The detail view shows:

• Overview cards -- At-a-glance counts for agent nodes and pipelines assigned to this environment.
• Vector Nodes table -- All nodes registered in this environment with their name, host address, status, and last-seen timestamp. Click a node name to jump to its fleet detail page.
• Agent Enrollment -- Generate or revoke the enrollment token that agents use to connect to this environment.
• Secret Backend -- Configure how pipelines resolve secret references (see below).
• Secrets & Certificates -- Manage the secrets and TLS certificates available to pipelines in this environment.

You can edit the environment name or delete the environment from the detail page header.

Agent enrollment tokens

Before an agent can connect to an environment, you must generate an enrollment token on the environment detail page. The token is displayed once -- copy it immediately.

Linux (binary)

The install script downloads the agent binary, verifies its checksum, installs Vector if it is not already present, and creates a systemd service:

curl -sSfL https://raw.githubusercontent.com/TerrifiedBug/vectorflow/main/agent/install.sh | \
  sudo bash -s -- --url https://your-vectorflow-instance --token <enrollment-token>

Docker

docker run -d --name vf-agent --restart unless-stopped \
  -e VF_URL=https://your-vectorflow-instance \
  -e VF_TOKEN=<enrollment-token> \
  -v /var/lib/vf-agent:/var/lib/vf-agent \
  ghcr.io/terrifiedbug/vectorflow-agent:latest

You can regenerate or revoke the token at any time. Revoking a token prevents new agents from enrolling, but already-connected agents continue operating until their individual node tokens are revoked from the Fleet page.

Secret backends

Each environment can use a different backend for resolving secret references in pipeline configurations:

Secrets per environment

Secrets are scoped to individual environments. The same secret name can hold different values in each environment. For example, you might have an ELASTICSEARCH_API_KEY secret that points to a test cluster in your dev environment and a production cluster in your production environment.

Manage secrets from the Secrets & Certificates section on the environment detail page.

Pipeline promotion

You can copy a pipeline from one environment to another using the Promote to... action on the Pipelines page. This is the recommended workflow for moving validated configurations through your lifecycle stages (e.g., dev to staging to production).

Deploy approval

Environments can require approval before pipelines are deployed. This is useful for production environments where you want a second pair of eyes on every configuration change. Approval and deployment are separate actions -- a reviewer approves the request, and then anyone with deploy access can execute the deployment.

Enabling approval

When enabled:

• Users with the Editor role will see a Request Deploy button instead of Publish to Agents in the deploy dialog. Their deploy requests are queued for review.
• Any team member with deploy access (editor or admin) can approve a pending request. Approval does not automatically deploy -- it marks the request as ready.
• Once approved, any team member with deploy access can deploy the approved request. The deploy dialog shows a Deploy button for approved requests.
• Approved requests can also be cancelled by anyone with deploy access if the deployment is no longer needed.
• Users with the Admin role can deploy directly (no approval needed), bypassing the approval flow entirely.
• A Pending Approval or Approved badge appears on the pipeline list and in the pipeline editor toolbar to indicate the request status.

Deploy tracking

VectorFlow tracks who actually deployed a pipeline separately from who approved it. The deploy history records:

• Requested by -- the user who submitted the deploy request
• Approved by -- the user who approved the request
• Deployed by -- the user who executed the deployment
• Status -- the request lifecycle: PENDING → APPROVED → DEPLOYED (or REJECTED / CANCELLED)

This separation provides a clear audit trail for compliance, especially in regulated environments where you need to know exactly who authorized and executed each deployment.

For more details on how the approval workflow operates, see Pipelines -- Deploy approval workflows.

Editing and deleting environments

• Edit -- Click the Edit button on the environment detail page to rename the environment or change its secret backend configuration.
• Delete -- Click the Delete button to permanently remove the environment. You must have the Admin role on the team to delete an environment.

Git Integration

VectorFlow can automatically commit pipeline YAML files to a Git repository whenever a pipeline is deployed or deleted. This provides an audit trail, version history, and hook points for external CI/CD workflows.

Setup

How It Works

When you deploy a pipeline, VectorFlow commits the generated YAML to {environment-name}/{pipeline-name}.yaml in the configured repository. When you delete a pipeline, the file is removed with a commit.

GitOps Mode

Each environment has a GitOps Mode setting that controls the direction of Git synchronization:

When Bi-directional mode is enabled, a webhook URL and secret are generated. Configure these in your GitHub repository webhook settings to enable automatic pipeline imports on push. See the GitOps guide for detailed setup instructions.