Skip to main content

​
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

# 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

# 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

# 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.