Environment

What is an Environment?

An Environment in Tool Forge is an isolated context within a workspace where your tools and agents run. Environments let you separate your development workflow from production, ensuring that testing and development activities never interfere with live operations.

Each workspace can contain multiple environments, typically organized by stage:

Workspace: "Acme Corp"
├── Environment: Development
│   ├── Tools (connected via `toolforge dev`)
│   ├── API Key: pk_test_xxx
│   └── Runners: Local development machines
│
└── Environment: Production
    ├── Tools (deployed via `toolforge deploy`)
    ├── API Key: sk_live_xxx
    └── Runners: Production servers

Environment Types

Tool Forge supports two types of environments, each designed for a specific purpose:

Development Environment

Development environments are for building, testing, and iterating on your tools.

# Connect to a development environment
TOOL_FORGE_API_KEY=pk_test_xxx bun dev

Production Environment

Production environments are for deploying stable tools that your team relies on.

# Deploy to a production environment
TOOL_FORGE_API_KEY=sk_live_xxx bun start

Why Separate Environments?

The separation between development and production environments is intentional and enforced for several important reasons:

1. Prevent Tool Disruption

When you run toolforge dev, your local runner connects to Tool Forge and registers your tools. If you connect to a production environment:

• Tool conflicts: Your development version may override or conflict with the deployed version
• Session interruptions: Users actively running a tool may experience disconnections or errors
• Inconsistent behavior: Half-finished features or buggy code could affect live operations

2. Protect User Experience

Imagine a support team member is processing a customer refund using your production tool. If a developer connects their local machine to the same environment:

• The tool might restart mid-operation
• Form inputs could be lost
• The refund might fail or be processed incorrectly
• The support team loses trust in the tooling

3. Enable Safe Iteration

With separate environments, you can:

• Break things safely in development without affecting anyone
• Test edge cases without real consequences
• Experiment with new features before rolling them out
• Debug issues using production-like data in a safe context

4. Clear Deployment Pipeline

The environment separation creates a natural deployment workflow:

Development → Testing → Production
     ↓            ↓           ↓
toolforge dev  Review    toolforge deploy

Environment Components

Each environment contains several key components:

Tools and Agents

Your tools and agents are registered within a specific environment. When you run toolforge dev or toolforge deploy, the runner:

1. Connects to Tool Forge using your API key
2. Registers all tools found in your tools/ directory
3. Makes them available in the dashboard for that environment

API Keys

Each environment has its own set of API keys:

You can generate multiple API keys per environment for:

• Different team members
• Different deployment servers
• Key rotation without downtime

Runners

A Runner is an instance of the Tool Forge SDK that's connected to an environment. When you run toolforge dev or toolforge deploy, your machine becomes a runner.

The dashboard shows:

• Active runners connected to the environment
• Runner status (online/offline)
• Resource usage (CPU, memory)
• Active sessions being handled by each runner

Tool Sessions

A Tool Session represents a single execution of a tool. The environment tracks:

• Who started the session
• When it started and ended
• Current status (running, completed, failed)
• Which runner handled it

Creating an Environment

To create a new environment:

1. Navigate to your workspace in the dashboard
2. Click Create Environment
3. Enter a name (e.g., "Development", "Staging", "Production")
4. Select the environment type:
   • Development for toolforge dev
   • Production for toolforge deploy
5. Click Create

After creating the environment, generate an API key and add it to your project's .env file.

Managing API Keys

Generating Keys

1. Go to your environment in the dashboard
2. Navigate to API Keys
3. Click Generate New Key
4. Give it a descriptive name (e.g., "Local Dev - John", "Production Server 1")
5. Copy the key immediately—it won't be shown again

Key Security

• Never commit API keys to version control
• Use environment variables or secret management tools
• Rotate keys regularly, especially for production
• Revoke unused keys when team members leave or servers are decommissioned

# .env (never commit this file)
TOOL_FORGE_API_KEY=pk_test_your_key_here

Best Practices

Environment Naming

Use clear, descriptive names:

• ✅ Development, Staging, Production
• ✅ Local Testing, QA, Live
• ❌ env1, test, my-env

Recommended Setup

For most teams, we recommend this environment structure:

API Key Management

• One key per developer for development environments
• Separate keys for each production server
• Document which keys are used where
• Set up alerts for key usage anomalies

Next Steps

• Tools - Learn about building tools in Tool Forge
• Agents - Create multi-step workflows with context and branching
• Runners - Understand how runners connect your tools to Tool Forge
• Workspace - Learn about the parent organization structure
• Quick Start - Connect your first tool to an environment
• Build from Scratch - Set up a Tool Forge project manually