Skip to main content
POST
/
orgs
/
{organization}
/
servers
/
{server}
/
background-processes
Create background process
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://forge.laravel.com/api/orgs/{organization}/servers/{server}/background-processes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Custom command runner',
    'command' => 'php artisan custom:command',
    'user' => 'forge',
    'processes' => 1,
    'startsecs' => 10,
    'stopwaitsecs' => 10,
    'stopsignal' => 'SIGTERM'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
{
  "data": {
    "id": "<string>",
    "type": "backgroundProcesses",
    "attributes": {
      "command": "php artisan queue:work database",
      "user": "forge",
      "directory": "/home/forge/forge.laravel.com",
      "processes": 3,
      "status": "running",
      "created_at": "2025-07-29T09:00:00Z"
    }
  }
}

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

organization
string
required

The organization slug

server
integer
required

The server ID

Body

application/json
name
string
required

The name of the background process.

Example:

"Custom command runner"

command
string
required

The command to run.

Example:

"php artisan custom:command"

user
enum<string>
required

The user to run the background process as.

Available options:
root,
forge
Example:

"forge"

processes
integer
required

The number of processes to run.

Required range: x >= 1
Example:

1

startsecs
integer

The number of seconds to wait before starting the process.

Required range: x >= 0
Example:

10

stopwaitsecs
integer

The number of seconds to wait before stopping the process.

Required range: x >= 0
Example:

10

stopsignal
string | null

The signal to send to stop the process.

Example:

"SIGTERM"

Response

BackgroundProcessResource

data
object
required
I