Swine
Project description
Swine Library
An SDK for starting and interacting with Pig Windows VMs.
Note: This API (and associated infra) is not stable, and may change at any time. Use at your own risk.
Installation
pip install swine
This installs both the swine
Python SDK, and the swine
CLI.
Quick Start
First, set up your API key:
export PIG_SECRET_KEY=your_api_key
The following code snippet will launch your first VM and interact with it:
from swine import VM
vm = VM()
print("Starting VM...")
# The initial boot will take a few minutes.
conn = vm.connect()
# Once it's ready, you can start sending commands
conn.mouse_move(100, 100) # Move mouse to coordinates
conn.left_click(100, 100) # Click at coordinates
conn.type("Hello, World!")
This VM will remain running. You can see it with the CLI:
swine ls
You may resume work on it by referencing it by ID:
vm = VM(id="VM-ABCDEFG-ABCDEFG-ABCDEFG")
conn = vm.connect()
conn.type("Hello Again!")
Lastly, please clean up after yourself and stop your running VMs:
vm.stop() # Persists to disk
# or
vm.terminate() # Deletes the disk, making the VM no longer usable.
For automated scripts where you want to ensure VMs are properly cleaned up, you can use the context manager:
with VM().session() as conn:
conn.mouse_move(100, 100)
conn.left_click(100, 100)
# VM automatically stops when leaving this block
Tip: During development and exploration, prefer using the imperative API (vm.start(), vm.stop()
) so you can watch the VM and experiment. Use the context manager (vm.session()
) once you're ready to automate tasks.
The Swine CLI
Since we don't have a UI, the pip install swine
comes with a CLI for managing VMs:
swine ls
ID Status Created
-------------------------- -------- ----------------
VM-6F25BH9-VHENR80-05CRX4Z Running 2025-01-16 06:47
VM-6F228MS-Q0EEQR0-02JT39X Running 2025-01-15 23:45
VM-6F1ZD69-RZFZC80-0367645 Stopped 2025-01-15 17:15
VM-6F1YRA8-QKF7RR0-06MW6CB Stopped 2025-01-15 15:46
swine ls
swine create
swine start <vm_id>
swine stop <vm_id>
swine terminate <vm_id>
These commands map directly to the SDK VM methods.
Main Classes
VM
VMs represent actual VM infrastructure on the Pig platform.
vm = VM(
id=None, # Optional: If you want to point to an existing Pig VM
image=None, # Optional: Windows image configuration
temporary=False, # Whether to delete VM after use in a .session()
api_key=None # Your API key (or use PIG_SECRET_KEY env var)
)
Instantiating VM() will create an empty VM client object.
Manage the cloud lifecycle of the VM with basic methods:
create()
: Creates a new VM on Pig and performs its initial boot- Sets
vm.id
on the client object, tying it to the newly created machine.
- Sets
start()
: Starts the VM. No-op if already runningstop()
: Stops the VM. No-op if already stoppedterminate()
: Terminates and deletes the VM. It will no longer be usable
The VM lifecycle can be managed with the session
context manager:
with vm.session() as conn:
# do stuff with conn
- Creates VM if necessary
- Starts VM if necessary
- Yields a
Connection
object - Stops the VM on scope exit
This ensures you don't leave machines running.
Alternatively, you can call connect
directly:
conn = vm.connect()
# do stuff with conn
- Creates VM if necessary
- Starts VM if necessary
- Returns a
Connection
object - Prints URL where you can watch the desktop
This will leave the VM running, and it's up to you to stop it.
Connection
Connections are the interface for sending commands into a running VM.
You create connections with:
conn = vm.connect()
# or
with vm.session() as conn:
# ...
Agent actions:
type(str)
: Type text into VMcursor_position()
: Returns current cursor position as (x, y) tuple.mouse_move(x, y)
: Move mouse to coordinatesleft_click(x, y)
: Left click at coordinatesleft_click_drag(x, y)
: Click at current position and drag to new coordinatesdouble_click(x, y)
: Double click at coordinatesright_click(x, y)
: Right click at coordinatesscreenshot() -> bytes
: Take a screenshot. Returns bytes in PNG format'
Control guards: At times, it may be necessary for the agent to yield control of the connection to a human operator. This helps ensure safety and accuracy. When control is yielded, you (the human) can interract with the VM in the browser, and then grant control back to the agent.
yield_control()
: Yields control of the connection to a human operator. This blocks all state-changing actions by the agent until the control is given back.await_control()
: Awaits for control of the connection to be given back to the agent. Best used directly afteryield_control()
.
Getters:
width
: Get the width of the VM (1024)height
: Get the height of the VM (768)
Advanced Usage
Custom Images
You can boot Windows VMs with custom images:
windows = (
Windows(version="2025") # Specify Windows version
.install("Office") # Add applications to install
)
vm = VM(image=windows)
vm.create() # Boots Windows 2025 with Office installed
Temporary VMs
If using the vm.session()
context manager, you can flag the VM to be terminated after use with temporary=True
:
vm = VM(temporary=True)
with vm.session() as conn:
# VM is terminated after this block
Note existing VM IDs cannot be used as temporary VMs.
Environment Variables
PIG_SECRET_KEY
: Your API keyPIG_BASE_URL
: Custom API URL (default: https://api.pig.dev)PIG_UI_BASE_URL
: Custom UI URL (default: https://pig.dev)
Schema
Swine is best used as Tools called via Anthropic Computer Use.
To assist in configuring the computer use environment, we provide the tool specification:
from swine.schema import claude
# claude = {
# "properties": {
# "action": {
# "description": """The action to perform. The available actions are:
# * `type`: Type a string of text on the keyboard.
# * `cursor_position`: Get the current (x, y) pixel coordinate of the cursor on the screen.
# ...
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file swine-0.1.4.tar.gz
.
File metadata
- Download URL: swine-0.1.4.tar.gz
- Upload date:
- Size: 9.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.0.1 CPython/3.13.1
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
d143a57430dd7aebae8228891b3041ab93ab1bc43a4dbf287a344f10897a418b
|
|
MD5 |
f6957f54c2d43bf5e9d99e52a957c33e
|
|
BLAKE2b-256 |
d8f8432c6506c5d88af2992b2797f9e9393f77e00eb13bca21a402d13488917c
|
File details
Details for the file swine-0.1.4-py3-none-any.whl
.
File metadata
- Download URL: swine-0.1.4-py3-none-any.whl
- Upload date:
- Size: 9.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.0.1 CPython/3.13.1
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
1f20c7ba4b12e94a6ccd9fa7aa64356277f6f3b1d46b243f07b369dca4383f4c
|
|
MD5 |
a0c1ee5b48ef4f6c58af528e37977e1c
|
|
BLAKE2b-256 |
715b7e6f190c8d49d03b361957233d46b6fe3bfd93b1e030788b594a36038a3e
|