# Simulator Management

Create New Simulator

```bash
# Create basic simulator
composabl sim new \
  --name reactor-sim \
  --description "Chemical reactor simulator" \
  --location ./simulators/

# Create Docker-ready simulator
composabl sim new \
  --name reactor-sim \
  --description "Chemical reactor simulator" \
  --location ./simulators/ \
  --docker
```

#### Generated Simulator Structure

Basic simulator:

```
reactor-sim/
├── pyproject.toml
├── README.md
└── reactor_sim/
    ├── __init__.py
    ├── sim.py       # Environment implementation
    └── sim_impl.py  # AMESA interface
```

Docker simulator adds:

```
reactor-sim/
├── Dockerfile
├── main.py
├── docker/
│   └── sim-start.sh
└── module/
    └── reactor_sim/
        └── ...
```

#### Run Simulator

```bash
# Run from current directory
composabl sim run

# Run specific simulator
composabl sim run ./simulators/reactor-sim/

# Run with options
composabl sim run \
  --path ./simulators/reactor-sim/ \
  --host 0.0.0.0 \
  --port 8080 \
  --protocol grpc \
  --env-init '{"difficulty": "medium", "seed": 42}'
```

#### Validate Simulator

```bash
# Validate simulator in current directory
composabl sim validate

# Validate specific path
composabl sim validate ./simulators/reactor-sim/

# Validate running simulator
composabl sim validate --address localhost:1337 --protocol grpc
```

Validation checks:

* Proper interface implementation
* Space definitions
* Reset/step functionality
* Scenario handling
* Rendering capabilities

#### Benchmark Simulator

```bash
# Benchmark current directory
composabl sim benchmark

# Benchmark with options
composabl sim benchmark \
  --samples 5000 \
  --address localhost:1337

# Output: Samples per second: 15243.7
```

#### Docker Simulator Management

**Start Simulator Container**

```bash
# Start simulator
composabl sim start sim-cartpole

# Start with historian
composabl sim start sim-cartpole --enable-historian

# Stream logs
composabl sim start sim-cartpole --stream

# Get container name only
composabl sim start sim-cartpole --show-name
```

**List Running Simulators**

```bash
# Show all running simulators
composabl sim status

# Example output:
Name          Image                    Address         Ports          Historian  Version
sim-cartpole  composabl/sim-cartpole  localhost:32768  32768->1337   True       latest
sim-reactor   composabl/sim-reactor   localhost:32769  32769->1337   False      v2.1.0
```

**Get Simulator Status**

```bash
# Specific simulator status
composabl sim status sim-cartpole

# Get connection string only
composabl sim status sim-cartpole --moniker
# Output: localhost:32768
```

**View Logs**

```bash
# View logs
composabl sim logs sim-cartpole

# Stream logs
composabl sim logs sim-cartpole --stream
```

**Stop Simulators**

```bash
# Stop specific simulator
composabl sim stop sim-cartpole

# Stop all simulators
composabl sim stop
```

#### Get Simulator Information

```bash
# Get info from running simulator
composabl sim info --address localhost:1337

# Get info from Docker image
composabl sim info --name sim-cartpole

# Output:
Simulator Info
- Address: localhost:1337
- Env ID: CartPole-v1
- Is Port Open? True
- Is Channel Available? True

Space Info
- Sensor Space: Box([-4.8, -inf, -0.418, -inf], [4.8, inf, 0.418, inf])
- Action Space: Discrete(2)

Sensors
  Sensor("cart_position", "")
  Sensor("cart_velocity", "")
  Sensor("pole_angle", "")
  Sensor("pole_angular_velocity", "")
```

#### Get Space Mappings

```bash
# From running simulator
composabl sim mappings --address localhost:1337

# From Docker image
composabl sim mappings --image composabl/sim-demo

# Output (JSON):
{
  "action_space": {
    "space": "Discrete(2)",
    "mappings": [
      {"name": "action", "type": "discrete", "values": [0, 1]}
    ]
  },
  "sensor_space": {
    "space": "Box(...)",
    "mappings": [
      {"name": "cart_pos", "type": "continuous", "low": -4.8, "high": 4.8},
      {"name": "cart_vel", "type": "continuous", "low": -inf, "high": inf},
      {"name": "pole_angle", "type": "continuous", "low": -0.418, "high": 0.418},
      {"name": "pole_vel", "type": "continuous", "low": -inf, "high": inf}
    ]
  }
}
```

#### List Available Simulators

```bash
# List local Docker images
composabl sim list --local

# List from platform
composabl sim list

# Output:
Name              Version  Description                  Status      UUID
reactor-sim       2        Chemical reactor simulator   READY       abc123
navigation-sim    1        Robot navigation simulator   BUILDING    def456
```

#### Publish Simulator

```bash
# Publish to platform
composabl sim publish ./simulators/reactor-sim/
```

#### Delete Simulator

```bash
# Interactive deletion
composabl sim delete
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amesa.com/reference/cli-reference/simulator-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.