---
title: "Install an environment listing into your workspace [write]"
method: POST
path: "/catalog/environments/{handle}/install"
tags: ["catalog"]
---

# Install an environment listing into your workspace \[write\]

`POST /catalog/environments/{handle}/install`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/catalog/environments/{handle}/install`
- Auth: HTTP bearer

Creates a copy of the listed environment in the caller's workspace that `extends` the original, so composition (packages, tool policy, networking) is applied at write time; another workspace's listing is composed from its approved version. A second install of the same listing by the same workspace is idempotent and returns the existing copy. Answers 404 when the shelf is not enabled or the listing is not found. Answers 503 `not_migrated` until the shelf migration is applied.

## Path parameters

- `handle` string, required

## Response `201`

Created

- object
  - `environment` Environment, required
    - `id` string, required: env_…
    - `name` string, required
    - `config` object, required: `packages` are installed into the image at build time — an environment is built when it is created and rebuilt when its config changes, so a session starting from it pays no install cost. `networking` is the egress policy its sessions run under; `limited` needs `allow_package_managers` when packages are declared, or the install could never succeed.
      - `type` 'cloud'
      - `packages` object
        - `apt` string[]
        - `pip` string[]
        - `npm` string[]
      - `networking` union
        - object
          - `type` 'unrestricted', required
        - object
          - `type` 'limited', required
          - `allowed_hosts` string[]
          - `allow_mcp_servers` boolean
          - `allow_package_managers` boolean
    - `is_default` boolean, required: Whether a new session that names no environment uses this one. At most one per workspace; setting it on one clears it on the others.
    - `extends` string, nullable, required: The env_… id of the parent environment this one extends, or null. Immutable after create. Child packages, tools.disabled and networking compose on the parent's at write time.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/catalog/environments/:handle/install/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/0d435187cd55?raw)