Core machines are Linux and Windows-based virtual machines (VMs) that run on top of virtualized hardware. Each machine you create is a new server or desktop instance you can use, either standalone or as part of a larger, cloud-based infrastructure.
This command creates a new Paperspace virtual machine.
If you are using an individual account, you are assigned as the owner of the machine.
If you are a team administrator, you must specify the user that should be assigned to the machine, either by specifying a user id, or by providing an email address, password, first name and last name for the creation of a new user on the team.
Only account administrators may create machines. Team members cannot create machines themselves.
paperspace machines create \
--apiKey "edc20a51d9b2145..." \
--region "East Coast (NY2)" \
--machineType "P4000" \
--size 50 \
--billingType "hourly" \
--machineName "My Machine 1" \
--templateId "tbu200wi" \
--teamId "tewr3st2z"
curl -X POST 'https://api.paperspace.io/machines/createSingleMachinePublic' \
-H 'X-Api-Key: edc20a51d9b2145...' \
-H 'Content-Type: application/json' \
--data-raw '{
"region": "East Coast (NY2)",
"machineType": "P4000",
"size": 50,
"billingType": "hourly",
"machineName": "My Machine 1",
"templateId": "tbu200wi",
"teamId": "tewr3st2z"
}'
paperspace.machines.create(
{
region: "East Coast (NY2)",
machineType: "P4000",
size: 50,
billingType: "hourly",
machineName: "My Machine 1",
templateId: "tbu200wi",
teamId: "tewr3st2z",
},
function (err, res) {
// handle error or result
}
);
Name | Type | Attributes | Description |
---|---|---|---|
region |
string | Name of the region. Valid entries: West Coast (CA1) , East Coast (NY2) , or Europe (AMS1) . |
|
machineType |
string | Machine type. Value entries are Air , Standard , Pro , Advanced , GPU+ , P4000 , P5000 , P6000 , V100 , C1 , C2 , C3 , C4 , C5 , C6 , C7 , C8 , C9 , or C10 . You cannot use Windows templates to create CPU-only machine types ‘C1’ - ‘C10’. |
|
size |
number | Storage size for the machine in GB. | |
billingType |
string | hourly billing. |
|
machineName |
string | A memorable name for this machine. | |
templateId |
string | Template ID of the template to use for creating this machine. | |
teamId |
string | optional | Required if creating this machine for a team |
assignPublicIp |
boolean | optional | Assign a new public ip address on machine creation. Cannot be used with dynamicPublicIp . |
dynamicPublicIp |
boolean | optional | Assigns a new public IP address on machine start and releases it from the account on machine stop. Cannot be used with assignPublicIp . |
startOnCreate |
boolean | optional | Start the VM immediately after creation. Defaults to true . |
networkId |
string | optional | If creating on a specific network specify its ID |
scriptId |
string | optional | The script ID of a script to be run on startup. See the Script Guide for more info on using scripts. |
userId |
string | optional | If assigning to an existing user other than yourself specify the user ID (mutually exclusive with email , password , firstName ,lastName ). |
email |
string | optional | If creating a new user for this machine specify their email address (mutually exclusive with userId ). |
password |
string | optional | If creating a new user specify their password (mutually exclusive with userId ). |
firstName |
string | optional | If creating a new user specify their first name (mutually exclusive with userId ). |
lastName |
string | optional | If creating a new user specify their last name (mutually exclusive with userId ). |
notificationEmail |
string | optional | Send a notification to this email address when complete. |
takeInitialSnapshot |
boolean | optional | Take a snapshot of the VM at first boot. |
markSnapshotAsRestorePoint |
boolean | optional | Use initial snapshot as a restore point for the VM. If this is true takeInitialSnapshot must be true and restorePointFrequency must be specified. |
restorePointFrequency |
string | optional | How often the VM’s restore point should be used. Valid options: shutdown . |
enableNvlink |
boolean | optional | Enable NVLink on compatible machine types. |
The created machine JSON object
{
"id": "psazmnxdy",
"name": "My Machine 1",
"os": null,
"ram": null,
"cpus": 1,
"gpu": null,
"storageTotal": null,
"storageUsed": null,
"machineType": "P4000",
"usageRate": "P4000 hourly",
"shutdownTimeoutInHours": 168,
"shutdownTimeoutForces": false,
"performAutoSnapshot": false,
"autoSnapshotFrequency": null,
"autoSnapshotSaveCount": null,
"dynamicPublicIp": false,
"agentType": "LinuxHeadless",
"dtCreated": "2022-03-14T15:09:51.974Z",
"state": "provisioning",
"updatesPending": false,
"networkId": null,
"privateIpAddress": null,
"publicIpAddress": null,
"region": null,
"scriptId": null,
"dtLastRun": null,
"restorePointSnapshotId": null,
"restorePointFrequency": null
}
Start an individual machine. If the machine is already started, this action is a no-op. If the machine is off, it is booted up. This action can only be performed by the user who owns the machine.
paperspace machines start \
--apiKey "edc20a51d9b2145..." \
--machineId "psfj3c701"
curl -X POST 'https://api.paperspace.io/machines/psfj3c701/start' \
-H 'X-Api-Key: edc20a51d9b2145...'
paperspace.machines.start(
{
machineId: "psfj3c701",
},
function (err, res) {
// handle error or result
}
);
Name | Type | Description |
---|---|---|
machineId |
string | Id of the machine to start |
Stop an individual machine. If the machine is already stopped or has been shut down, this action is a no-op. If the machine is running, it is stopped and any users logged in are immediately kicked out. This action can only be performed by the user who owns the machine.
paperspace machines stop \
--apiKey "edc20a51d9b2145..." \
--machineId "psfj3c701"
curl -X POST 'https://api.paperspace.io/machines/psfj3c701/stop' \
-H 'X-Api-Key: edc20a51d9b2145...'
paperspace.machines.stop(
{
machineId: "psfj3c701",
},
function (err, res) {
// handle error or result
}
);
Name | Type | Description |
---|---|---|
machineId |
string | Id of the machine to shut down |
Restart an individual machine. If the machine is already restarting, this action requests the machine be restarted again. This action can only be performed by the user who owns the machine.
paperspace machines restart \
--apiKey "edc20a51d9b2145..." \
--machineId "psfj3c701"
curl -X POST 'https://api.paperspace.io/machines/psfj3c701/restart' \
-H 'X-Api-Key: edc20a51d9b2145...'
paperspace.machines.stop(
{
machineId: "psfj3c701",
},
function (err, res) {
// handle error or result
}
);
Parameters
Name | Type | Description |
---|---|---|
machineId |
string | Id of the machine to restart |
Destroy the machine with the given id. When this action is performed, the machine is immediately shut down and marked for deletion from the datacenter. Any snapshots that were derived from the machine are also deleted. Access to the machine is terminated immediately and billing for the machine is prorated to the hour. This action can only be performed by the user who owns the machine, or in the case of a team, the team administrator.
paperspace machines destroy \
--apiKey "edc20a51d9b2145..." \
--machineId "psfj3c701"
curl -X POST 'https://api.paperspace.io/machines/psfj3c701/destroyMachine' \
-H 'X-Api-Key: edc20a51d9b2145...'
paperspace.machines.destroy(
{
machineId: "psfj3c701",
},
function (err, res) {
// handle error or result
}
);
Name | Type | Attributes | Description |
---|---|---|---|
machineId |
string | The id of the machine to destroy | |
releasePublicIp |
boolean | optional | releases any assigned public ip address for the machine; defaults to false |
Update attributes of a machine.
paperspace machines update \
--apiKey "edc20a51d9b2145..." \
--machineId "psec02yp2" \
--machineName "New Machine Name"
curl -X POST 'https://api.paperspace.io/machines/psec02yp2/updateMachinePublic' \
-H 'X-Api-Key: edc20a51d9b2145...' \
-H 'Content-Type: application/json' \
--data-raw '{"machineName": "New Machine Name"}'
paperspace.machines.update(
{
machineId: "psec02yp2",
machineName: "New Machine Name",
},
function (err, res) {
// handle error or result
}
);
Name | Type | Attributes | Description |
---|---|---|---|
machineId |
string | Id of the machine to update | |
machineName |
string | optional | New name for the machine |
shutdownTimeoutInHours |
number | optional | Number of hours before machine is shutdown if no one is logged in via the Paperspace client |
shutdownTimeoutForces |
boolean | optional | Force shutdown at shutdown timeout, even if there is a Paperspace client connection |
autoSnapshotFrequency |
number | optional | One of ‘hour’, ‘day’, ‘week’, or null |
autoSnapshotSaveCount |
number | optional | Number of snapshots to save |
performAutoSnapshot |
boolean | optional | Perform auto snapshots |
dynamicPublicIp |
boolean | optional | If true, assigns a new public ip address on machine start and releases it from the account on machine stop |
assignPublicIp |
boolean | optional | If true, assigns a new static public ip address for the machine |
List information about all machines available to either the current authenticated user or the team, if the user belongs to a team. The list method takes an optional first argument to limit the returned machine objects.
This API supports pagination using limit
and skip
. The default limit is 1000 items. To retrieve more than 1000 items, set your skip
parameter to a multiple of 1000. For example, to retrieve the 3rd page of 1000 items, you would pass { limit: 1000, skip: 2000 }
.
paperspace machines list \
--apiKey "edc20a51d9b2145..."
curl -X GET 'https://api.paperspace.io/machines/getMachines' \
-H 'X-Api-Key: edc20a51d9b2145...'
paperspace.machines.list(function (err, res) {
// handle error or result
});
Name | Type | Attributes | Description |
---|---|---|---|
limit |
number | optional | Number of items to return. Defaults to 1000. |
skip |
number | optional | Number of items in the list to skip. |
machineId |
string | optional | Machine id to match on. Note: must be specified as machineId , not id . |
name |
string | optional | Name to match on |
os |
string | optional | OS to match on |
ram |
string | optional | RAM value to match on |
cpus |
number | optional | CPU count to match on |
gpu |
string | optional | GPU to match on |
storageTotal |
string | optional | storageTotal value to match on |
storageUsed |
string | optional | storageUsed value to match on |
usageRate |
string | optional | usageRate value to match on |
shutdownTimeoutInHours |
number | optional | shutdownTimeoutInHours value to match on |
performAutoSnapshot |
boolean | optional | performAutoSnapshot value to match on, either true or false |
autoSnapshotFrequency |
string | optional | autoSnapshotFrequency value to match on |
autoSnapshotSaveCount |
number | optional | autoSnapshotSaveCount value to match on |
agentType |
string | optional | agentType value to match on |
dtCreated |
string | optional | datetime created value to match on |
state |
string | optional | state value to match on |
updatesPending |
boolean | optional | updatesPending value to match on |
networkId |
string | optional | networkId to match on |
privateIpAddress |
string | optional | privateIpAddress to match on |
publicIpAddress |
string | optional | publicIpAddress to match on |
region |
string | optional | region to match on |
userId |
string | optional | userId to match on |
teamId |
string | optional | teamId to match on |
scriptId |
string | optional | scriptId to match on |
dtLastRun |
string | optional | script date/time last run value to match on |
[
{
"id": "psec02yp2",
"name": "New Machine Name1",
"os": "",
"ram": "32212254720",
"cpus": 8,
"gpu": "Quadro P4000",
"storageTotal": "53687091200",
"storageUsed": "110080",
"machineType": "P4000",
"usageRate": "P4000 hourly",
"shutdownTimeoutInHours": 24,
"shutdownTimeoutForces": false,
"performAutoSnapshot": false,
"autoSnapshotFrequency": "day",
"autoSnapshotSaveCount": 1,
"dynamicPublicIp": false,
"agentType": "LinuxDesktop",
"dtCreated": "2022-03-14T15:47:53.852Z",
"state": "ready",
"updatesPending": false,
"networkId": "nng82wb",
"privateIpAddress": "10.64.1.99",
"publicIpAddress": "172.83.15.54",
"region": "East Coast (NY2)",
"scriptId": null,
"dtLastRun": null,
"restorePointSnapshotId": null,
"restorePointFrequency": null,
"internalId": 1713423
}
]
Show machine information for the machine with the given id.
The state property can take on the follow values:
off
starting
- machine is in the process of changing to the ready or serviceready
statestopping
- machine is in the process of changing to the off staterestarting
- combines stopping follow immediately by startingserviceready
- services are running on the machine but the Paperspace agent is not yet availableready
- services are running on machine and the Paperspace agent is ready to stream or accept loginsupgrading
- the machine specification are being upgraded, which involves a shutdown and startup sequenceprovisioning
- the machine is in the process of being created for the first timeThe updatesPending
property is either true or false and reflects whether the operating system has scheduled updates for the next machine state transition, e.g, stopping, starting, restarting, or upgrading.
Note: in some cases**,** the operating system can force installation of critical updates immediately upon a state transition, or automatically restart a machine to install updates. In such cases, the updatesPending
property may not always be set accurately by the underlying OS.
paperspace machines show \
--apiKey "edc20a51d9b2145..." \
--machineId "psec02yp2"
curl -X GET 'https://api.paperspace.io/machines/getMachinePublic?machineId=psec02yp2' \
-H 'X-Api-Key: edc20a51d9b2145...'
paperspace.machines.show(
{
machineId: "psec02yp2",
},
function (err, res) {
// handle error or result
}
);
Name | Type | Attributes | Description |
---|---|---|---|
machineId |
string | ID of the machine to show |
machine - The machine JSON object
Type object
{
"id": "psec02yp2",
"name": "New Machine Name1",
"os": "",
"ram": "32212254720",
"cpus": 8,
"gpu": "Quadro P4000",
"storageTotal": "53687091200",
"storageUsed": "110080",
"machineType": "P4000",
"usageRate": "P4000 hourly",
"shutdownTimeoutInHours": 24,
"shutdownTimeoutForces": false,
"performAutoSnapshot": false,
"autoSnapshotFrequency": "day",
"autoSnapshotSaveCount": 1,
"dynamicPublicIp": false,
"agentType": "LinuxDesktop",
"dtCreated": "2022-03-14T15:47:53.852Z",
"state": "ready",
"updatesPending": false,
"networkId": "nng82wb",
"privateIpAddress": "10.64.1.99",
"publicIpAddress": "172.83.15.54",
"region": "East Coast (NY2)",
"scriptId": null,
"dtLastRun": null,
"restorePointSnapshotId": null,
"restorePointFrequency": null,
"events": [
{
"name": "start",
"state": "done",
"errorMsg": "",
"handle": "fabd398a-9c8e-4565-95fa-5f07928564d8",
"dtModified": "2022-03-14T15:49:00.734Z",
"dtFinished": "2022-03-14T15:49:00.734Z",
"dtCreated": "2022-03-14T15:48:30.994Z"
},
{
"name": "create",
"state": "done",
"errorMsg": "",
"handle": "396ea947-9c10-4b63-a15b-574a9a9844bc",
"dtModified": "2022-03-14T15:48:31.026Z",
"dtFinished": "2022-03-14T15:48:31.026Z",
"dtCreated": "2022-03-14T15:47:53.852Z"
}
]
}
paperspace machines setAccessForUser \
--apiKey "edc20a51d9b2145..." \
--machineId "psec02yp2" \
--userId "ubx9ce8k" \
--enableAccess true
curl -X POST 'https://api.paperspace.io/machines/psec02yp2/setMachineAccess' \
-H 'X-Api-Key: edc20a51d9b2145...' \
-H 'Content-Type: application/json' \
--data-raw '{
"userId": "ubx9ce8k",
"enableAccess": "true"
}'
paperspace.machines.setAccessForUser(
{
machineId: "psec02yp2",
userId: "ubx9ce8k",
enableAccess: true,
},
function (err, res) {
// handle error or result
}
);
Name | Type | Attribute | Description |
---|---|---|---|
machineId |
string | required | Id of the machine to enable access |
userId |
string | required | Id of the user to enable machine access for |
enableAccess |
boolean | required | When true , the person is added as an accessor to the machine; when false the person is removed |
Get machine utilization data for the machine with the given id. Machine upgrades are not represented in utilization data.
paperspace machines utilization \
--apiKey "edc20a51d9b2145..." \
--machineId "psec02yp2" \
--billingMonth "2022-03"
curl -X GET 'https://api.paperspace.io/machines/getUtilization?machineId=psec02yp2&billingMonth=2022-03' \
-H 'X-Api-Key: edc20a51d9b2145...'
paperspace.machines.utilization(
{
machineId: "psec02yp2",
billingMonth: "2022-03",
},
function (err, res) {
// handle error or result
}
);
Name | Type | Attribute | Description |
---|---|---|---|
machineId |
string | required | Id of the machine to get utilization data for |
billingMonth |
string | required | Billing period to query in YYYY-MM format |
utilization - The utilization JSON object
Type object
{
"machineId": "psec02yp2",
"utilization": {
"machineId": "psec02yp2",
"secondsUsed": 8728.27191281319,
"hourlyRate": "0.51",
"billingMonth": "2022-03"
},
"storageUtilization": {
"machineId": "psec02yp2",
"secondsUsed": 8785.19808006287,
"monthlyRate": "5.00",
"billingMonth": "2022-03"
}
}
waitFor
Wait for the machine with the given id to enter a certain machine state. This action polls the server and returns only when we detect that the machine has transitioned into the given state. States available to check for are:
off
serviceready
- services are running on the machine but the Paperspace agent is not yet availableready
- services are running on machine and the Paperspace agent is ready to stream or accept loginsWhen the callback is called, the returned object is information about the machine.
paperspace machines waitfor \
--apiKey "edc20a51d9b2145..." \
--machineId "psec02yp2" \
--state "ready"
This method is not available via curl.
paperspace.machines.waitfor(
{
machineId: "psec02yp2",
state: "ready",
},
function (err, res) {
// handle error or result
}
);
Name | Type | Attributes | Description |
---|---|---|---|
machineId |
string | required | Id of the machine to wait for |
state |
string | required | Name of the state to wait for, either off , serviceready , ready |
machine - The machine JSON object
Type object
{
"id": "psec02yp2",
"name": "New Machine Name1",
"os": "",
"ram": "32212254720",
"cpus": 8,
"gpu": "Quadro P4000",
"storageTotal": "53687091200",
"storageUsed": "110080",
"machineType": "P4000",
"usageRate": "P4000 hourly",
"shutdownTimeoutInHours": 24,
"shutdownTimeoutForces": false,
"performAutoSnapshot": false,
"autoSnapshotFrequency": "day",
"autoSnapshotSaveCount": 1,
"dynamicPublicIp": false,
"agentType": "LinuxDesktop",
"dtCreated": "2022-03-14T15:47:53.852Z",
"state": "ready",
"updatesPending": false,
"networkId": "nng82wb",
"privateIpAddress": "10.64.1.99",
"publicIpAddress": "172.83.15.54",
"region": "East Coast (NY2)",
"scriptId": null,
"dtLastRun": null,
"restorePointSnapshotId": null,
"restorePointFrequency": null,
"events": [
{
"name": "start",
"state": "done",
"errorMsg": "",
"handle": "fabd398a-9c8e-4565-95fa-5f07928564d8",
"dtModified": "2022-03-14T15:49:00.734Z",
"dtFinished": "2022-03-14T15:49:00.734Z",
"dtCreated": "2022-03-14T15:48:30.994Z"
},
{
"name": "create",
"state": "done",
"errorMsg": "",
"handle": "396ea947-9c10-4b63-a15b-574a9a9844bc",
"dtModified": "2022-03-14T15:48:31.026Z",
"dtFinished": "2022-03-14T15:48:31.026Z",
"dtCreated": "2022-03-14T15:47:53.852Z"
}
]
}
Get machine availability for the given region and machine type. Note: availability is only provided for the dedicated GPU machine types. Also, not all machine types are available in all regions.
paperspace machines availability \
--apiKey "edc20a51d9b2145..." \
--region "East Coast (NY2)" \
--machineType "P4000"
curl -X GET 'https://api.paperspace.io/machines/getAvailability?region=East%20Coast%20(NY2)&machineType=P4000' \
-H 'X-Api-Key: edc20a51d9b2145...'
paperspace.machines.availability(
{
region: "East Coast (NY2)",
machineType: "P4000",
},
function (err, res) {
// handle error or result
}
);
Name | Type | Attributes | Description |
---|---|---|---|
region |
string | required | Name of the region: either ‘East Coast (NY2)’, ‘West Coast (CA1)’, or ‘Europe (AMS1)’ |
machineType |
string | required | Machine type: either ‘GPU+’, ‘P4000’, ‘P5000’, ‘P6000’, or ‘V100’ |
availability - The availability JSON object, containing a single boolean attribute, “available”. A value of true for “available” means machines of that type can currently be requested in that region. A value of false means that requests for that machine type are not currently available in that region.
Type object
{
"available": true
}