# Sourccey developer documentation

Scope: six developer subguides and agent context. Setup, Studio, assembly, and other pages are not included in this consolidated export; use the documentation index for those pages.

## Agent context

You are assisting with Vulcan Robotics Sourccey.
Official documentation: https://vulcanrobotics.ai/docs
Developer setup: https://vulcanrobotics.ai/docs/lerobot
Source: https://github.com/vulcan-forge/lerobot-vulcan

Read the relevant official docs and inspect the actual repository before proposing commands.
Confirm the user's hardware revision, software commit/version, OS, controller computer, robot computer, and intended task.
Do not invent CLI flags, hardware specifications, APIs, joint IDs, pinouts, or capabilities.
Label every command with its execution computer and shell; explain placeholders and expected results.
Do not initiate physical robot movement without explicit human approval and supervision.
Confirm the stopping procedure for the actual hardware revision before any motion.
Give a test and rollback procedure. Report discrepancies between docs and code instead of guessing.
Existing website commands are pending a pinned-source and physical-hardware walkthrough; do not treat their presence as proof of safety or compatibility.

---

# Teleoperate Sourccey

Verify the network, leader arms, robot, keyboard, and cameras together before collecting data.

Execution context: Controller computer; robot host must be prepared separately.

> Verification pending: existing website examples have not completed a pinned-source or physical-hardware walkthrough. Confirm software version, hardware revision, and actual stopping procedure. Do not assume emergency-stop or release-to-stop behavior. Explicit human approval and supervision are required before physical movement.

## Before you start

- sourccey-host is running on the robot computer.
- The robot workspace is clear and the emergency stop is within reach.
- Both leader arms are connected and calibrated.
- You know the robot IP and both leader-arm ports.

## Run teleoperation

Run this on the controller computer. Replace the example IP address and COM ports first.

```shell
uv run lerobot-teleoperate --robot.type=sourccey_client --robot.id=sourccey --robot.remote_ip=192.168.1.243 --teleop.type=bi_sourccey_leader --teleop.id=sourccey_leader --teleop.left_arm_port=COM5 --teleop.right_arm_port=COM6 --teleop_keyboard.type=keyboard --teleop_keyboard.id=sourccey_keyboard --fps=30 --display_data=true
```

## Keyboard controls

| Key | Action |
| --- | --- |
| W / S | Move forward / backward |
| A / D | Move left / right |
| Z / X | Rotate left / right |
| Q / E | Raise / lower the lift target |
| R / F | Increase / decrease base speed |
| N / M | Toggle left / right arm untorque |

## Readiness check

- Each leader arm moves only its matching robot arm.
- Base and lift keys move in the expected direction.
- Camera images update in the display.
- Releasing the controls stops motion.
- The host shows no repeated timeout or device errors.

Stop teleoperation with Ctrl+C. Fix any failed check before recording.

Website: https://vulcanrobotics.ai/docs/lerobot/teleoperate

Upstream reference (unpinned): https://github.com/vulcan-forge/lerobot-vulcan/blob/main/docs/sourccey/02-teleoperate.md


---

# Record a dataset

Collect a small, consistent set of demonstrations after teleoperation passes.

Execution context: Controller computer; robot host must be prepared separately.

> Verification pending: existing website examples have not completed a pinned-source or physical-hardware walkthrough. Confirm software version, hardware revision, and actual stopping procedure. Do not assume emergency-stop or release-to-stop behavior. Explicit human approval and supervision are required before physical movement.

## Before you record

Start with five short episodes so mistakes are inexpensive to correct. Keep the task wording, camera placement, starting area, and success condition consistent.

## Record a dataset

Replace the IP, ports, dataset ID, and task before running this on the controller.

```shell
uv run lerobot-record --robot.type=sourccey_client --robot.id=sourccey --robot.remote_ip=192.168.1.243 --teleop.type=bi_sourccey_leader --teleop.id=sourccey_leader --teleop.left_arm_port=COM5 --teleop.right_arm_port=COM6 --teleop_keyboard.type=keyboard --teleop_keyboard.id=sourccey_keyboard --dataset.repo_id=vulcan-studio/sourccey-demo-1 --dataset.num_episodes=5 --dataset.episode_time_s=60 --dataset.reset_time_s=15 --dataset.single_task="Fold the shirt" --dataset.fps=30 --dataset.push_to_hub=false --display_data=true
```

Keep push_to_hub=false for local data. Enable it when you intend to upload and are signed into the correct Hugging Face account.

## Recording controls

| Key | Action |
| --- | --- |
| Right Arrow | Save the current episode |
| Left Arrow | Discard and re-record |
| Escape | Stop recording |

## Dataset check

- All five episodes save successfully.
- No camera freezes or timing errors occur.
- Every saved episode completes the task.
- Control is uninterrupted throughout each episode.

Website: https://vulcanrobotics.ai/docs/lerobot/record

Upstream reference (unpinned): https://github.com/vulcan-forge/lerobot-vulcan/blob/main/docs/sourccey/03-record.md


---

# Replay an episode

Send recorded actions back to Sourccey and validate the dataset before training.

Execution context: Controller computer; robot host must be prepared separately.

> Verification pending: existing website examples have not completed a pinned-source or physical-hardware walkthrough. Confirm software version, hardware revision, and actual stopping procedure. Do not assume emergency-stop or release-to-stop behavior. Explicit human approval and supervision are required before physical movement.

## Prepare for replay

- Clear the full robot workspace.
- Keep the emergency stop within reach.
- Start sourccey-host on the robot computer.
- Restore the same physical setup used while recording.

## Replay an episode

Run this on the controller. Episode numbers are zero-based, so 0 is the first recording.

```shell
uv run lerobot-replay --robot.type=sourccey_client --robot.id=sourccey --robot.remote_ip=192.168.1.243 --dataset.repo_id=vulcan-studio/sourccey-demo-1 --dataset.episode=0
```

## Validate the episode

- The action sequence is smooth and recognizable.
- Arms, base, and lift move as recorded.
- The robot stops when replay finishes.
- There is no unexpected or unsafe motion.

Do not train if replay exposes incorrect feature mapping, unexpected lift behavior, or unsafe motion.

Website: https://vulcanrobotics.ai/docs/lerobot/replay

Upstream reference (unpinned): https://github.com/vulcan-forge/lerobot-vulcan/blob/main/docs/sourccey/04-replay.md


---

# Train a policy

Train an ACT policy from the dataset without connecting to the robot.

Execution context: Training computer.

> Verification pending: existing website examples have not completed a pinned-source or physical-hardware walkthrough. Confirm software version, hardware revision, and actual stopping procedure. Do not assume emergency-stop or release-to-stop behavior. Explicit human approval and supervision are required before physical movement.

## Choose a device

- Use cuda for a supported NVIDIA GPU.
- Use mps for Apple silicon.
- Use cpu for a CPU-only run.
- Lower batch_size if the device runs out of memory.

## Train an ACT policy

Run training on the controller or another computer that can access the dataset. sourccey-host is not required.

```shell
uv run lerobot-train \
  --dataset.repo_id=vulcan-studio/sourccey-demo-1 \
  --policy.type=act \
  --policy.device=cuda \
  --output_dir=outputs/train/act-sourccey-demo-1 \
  --job_name=act-sourccey-demo-1 \
  --batch_size=8 \
  --steps=20000 \
  --save_freq=5000 \
  --wandb.enable=false \
  --policy.push_to_hub=false
```

## Train X-VLA on a stronger GPU

If you have a stronger NVIDIA GPU with sufficient VRAM, we recommend fine-tuning the 0.9B-parameter X-VLA base model as the higher-capacity option. Install the X-VLA dependencies first:

```shell
uv sync --locked --extra sourccey-desktop --extra training --extra xvla
```

```shell
uv run lerobot-train \
  --dataset.repo_id=vulcan-studio/sourccey-demo-1 \
  --output_dir=outputs/train/xvla-sourccey-demo-1 \
  --job_name=xvla-sourccey-demo-1 \
  --policy.path=lerobot/xvla-base \
  --policy.dtype=bfloat16 \
  --policy.action_mode=auto \
  --policy.device=cuda \
  --policy.freeze_vision_encoder=false \
  --policy.freeze_language_encoder=false \
  --policy.train_policy_transformer=true \
  --policy.train_soft_prompts=true \
  --steps=20000 \
  --policy.push_to_hub=false
```

X-VLA starts from the pretrained lerobot/xvla-base checkpoint and uses bfloat16 to reduce memory use. If training runs out of memory, reduce the batch size before changing the model configuration.

## Check the output

Training should complete without dataset feature or video-decoding errors. The ACT example creates this model directory:

```shell
outputs/train/act-sourccey-demo-1/checkpoints/last/pretrained_model
```

Website: https://vulcanrobotics.ai/docs/lerobot/train

Upstream reference (unpinned): https://github.com/vulcan-forge/lerobot-vulcan/blob/main/docs/sourccey/05-train.md


---

# Roll out a policy

Give a trained policy supervised control of Sourccey for a short test.

Execution context: Controller computer; robot host must be prepared separately.

> Verification pending: existing website examples have not completed a pinned-source or physical-hardware walkthrough. Confirm software version, hardware revision, and actual stopping procedure. Do not assume emergency-stop or release-to-stop behavior. Explicit human approval and supervision are required before physical movement.

## Before rollout

- Clear the full workspace.
- Keep the emergency stop within reach.
- Start sourccey-host on the robot computer.
- Supervise the entire run.
- Begin with a 30-second duration.

## Run the policy

Run this on the controller. The task text, camera names, and action features must match the training dataset.

```shell
uv run lerobot-rollout --strategy.type=base --policy.path=outputs/train/act-sourccey-demo-1/checkpoints/last/pretrained_model --robot.type=sourccey_client --robot.id=sourccey --robot.remote_ip=192.168.1.243 --task="Fold the shirt" --duration=30 --fps=30 --device=cuda --display_data=true
```

## Extend safely

- The robot responds smoothly.
- It remains inside the expected workspace.
- It stops after 30 seconds.
- No feature-shape or camera errors occur.

Increase duration only after repeated short rollouts behave safely.

Website: https://vulcanrobotics.ai/docs/lerobot/rollout

Upstream reference (unpinned): https://github.com/vulcan-forge/lerobot-vulcan/blob/main/docs/sourccey/06-rollout.md


---

# Troubleshooting

Work from the top of the relevant section and run one diagnostic at a time.

Execution context: Check the execution computer for each diagnostic.

> Verification pending: existing website examples have not completed a pinned-source or physical-hardware walkthrough. Confirm software version, hardware revision, and actual stopping procedure. Do not assume emergency-stop or release-to-stop behavior. Explicit human approval and supervision are required before physical movement.

## Plugin

Reinstall the locked controller environment and verify the installed plugin version.

```shell
uv sync --locked --extra sourccey-desktop --extra training
```

```shell
uv run python -c "import importlib.metadata as m; print(m.version('lerobot-robot-sourccey'))"
```

## Network

Confirm the example IP was replaced, both computers share a network, and sourccey-host is still running.

```shell
ping 192.168.1.243
```

## Leader arms

Disconnect one leader arm and find the remaining port. Repeat for the other arm.

```shell
uv run lerobot-find-port
```

- Check the selected port.
- Check USB and motor power.
- Close other processes using the serial port.

## Cameras and hardware

With the host running, check cameras from the controller.

```shell
uv run python scripts/sourccey_check_eye_cameras.py --remote-ip 192.168.1.243
```

```shell
uv run python scripts/sourccey_check_arm_cameras.py --remote-ip 192.168.1.243
```

Stop sourccey-host before direct device checks on the robot computer.

## Datasets

Confirm the dataset ID is identical in record and train commands. Decode, consistency, and feature-cleanup errors should be resolved before training.

Website: https://vulcanrobotics.ai/docs/lerobot/troubleshooting

Upstream reference (unpinned): https://github.com/vulcan-forge/lerobot-vulcan/blob/main/docs/sourccey/troubleshooting.md