> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Organization & Configuration

> Structure and configure your Kubiya workspace

## Overview

Organization resources help you structure your Kubiya workspace, manage configurations, and control how resources are shared across teams and agents. These resources provide the organizational hierarchy for your platform.

## Projects

Projects are the top-level organizational unit in Kubiya. They group related agents, workflows, and resources together.

**Use projects to:**

* Organize resources by application, team, or business unit
* Share configurations across multiple agents
* Control access and permissions at scale
* Separate development, staging, and production resources

**Common operations:**

* Create and configure projects
* Assign agents and teams to projects
* Manage project-level settings

## Environments

Environments define the runtime context for agent execution. They specify:

* Environment variables
* Configuration values
* API endpoints
* Feature flags

**Environment types:**

* **Development**: For testing and experimentation
* **Staging**: For pre-production validation
* **Production**: For live operations

**Key features:**

* Environment inheritance and overrides
* Secret integration for sensitive values
* Dynamic variable resolution
* Multi-environment deployments

## Execution Environment

The execution environment provides runtime variable resolution for agents and teams. It:

* Resolves environment variables from multiple sources
* Merges project, team, and agent-specific configurations
* Handles secret injection securely
* Provides context-aware configuration

## Organization Hierarchy

```
Organization
└── Projects
    ├── Environments
    │   └── Variables & Secrets
    ├── Teams
    │   └── Agents
    └── Workflows
```

## Common Patterns

### Multi-Environment Setup

```bash theme={null}
# Create production environment
POST /api/v1/environments
{
  "name": "production",
  "display_name": "Production Environment",
  "description": "Production deployment environment",
  "tags": ["prod", "live"],
  "execution_environment": {
    "env_vars": {
      "LOG_LEVEL": "info",
      "DEPLOYMENT_ENV": "production"
    }
  }
}

# Create staging environment
POST /api/v1/environments
{
  "name": "staging",
  "display_name": "Staging Environment",
  "description": "Pre-production testing environment",
  "tags": ["staging", "test"],
  "execution_environment": {
    "env_vars": {
      "LOG_LEVEL": "debug",
      "DEPLOYMENT_ENV": "staging"
    }
  }
}
```

**Required fields**: `name`
**Note**: First environment triggers Temporal Cloud namespace provisioning

### Project-Based Organization

```bash theme={null}
# Create project for a team
POST /api/v1/projects
{
  "name": "Platform Engineering",
  "key": "PLAT",
  "description": "Infrastructure and platform automation",
  "goals": "Maintain reliable, scalable infrastructure",
  "visibility": "org",
  "default_model": "anthropic/claude-sonnet-4-5"
}
```

**Required fields**: `name`, `key`
**Note**: `key` must be 2-50 characters (e.g., "PLAT", "DEVOPS")

### Get Default Project

```bash theme={null}
# Get or create default project
GET /api/v1/projects/default
```

This automatically creates a default project if one doesn't exist.

## Best Practices

1. **Project Structure**: Align projects with your organizational structure
2. **Environment Strategy**: Use consistent environment names across projects
3. **Variable Management**: Use project-level variables for shared configuration
4. **Secret Handling**: Never store secrets in environment variables directly
5. **Access Control**: Set permissions at the project level for easier management

## Next Steps

Explore the API endpoints for projects, environments, and execution environment configuration.