Introduction
Managing remote servers usually means logging in through SSH (Linux) or RDP (Windows). While that works, it also means managing ports, credentials, and access controls.
Oracle Cloud Infrastructure (OCI) offers a cleaner option called Run Command.
OCI Run Command allows you to remotely execute commands or scripts on OCI Compute instances directly from the OCI Console, OCI CLI, or API — without logging in to the server manually.
This blog explains what OCI Run Command is, how it works, what is required, common statuses, troubleshooting, and best practices.
What is OCI Run Command?
OCI Run Command is a feature that lets you run commands remotely on an OCI Compute instance using the Oracle Cloud Agent installed on that server.
Examples:
hostname
whoami
systemctl restart nginx
df -h
Instead of connecting to the server manually, OCI sends the command securely through the cloud control plane.
Why Use Run Command?
OCI Run Command is useful when you want to:
Run quick administrative commands
Restart services
Collect logs
Check disk space / memory
Update configuration
Run scripts remotely
Troubleshoot servers without SSH/RDP access
Architecture Overview
Administrator
│
▼
OCI Console / OCI CLI
│
▼
Run Command Service
│
▼
OCI Instance Agent
│
▼
Compute Instance
│
┌───┴──────────────┐
▼ ▼
Object Storage Log Files
(Scripts) (Output)
Inline Commands vs Large Scripts
Use Inline Commands For:
hostname
uptime
df -h
systemctl status httpd
Use Object Storage Scripts For:
Application deployment
Package installation
Multi-step patching
Configuration enforcement
Long shell logic
Main Components Required
1. OCI Compute Instance
Target server where command will run.
2. Oracle Cloud Agent
Installed on OCI instance. This agent communicates with OCI services.
3. Run Command Plugin
Must be enabled inside Oracle Cloud Agent settings.
4. IAM Policies
Permissions are needed for:
User who creates command
Instance that consumes command
5. Dynamic Group
Used to grant permissions to the OCI instance itself.
Step 1: Enable Run Command Plugin
Go to:
OCI Console → Compute Instance → Oracle Cloud Agent
Enable:
Step 2: Create Dynamic Group
Example rule:
ALL {instance.compartment.id = ''}
This means all servers in that compartment join the Dynamic Group.
Step 3: Dynamic Group Policies
Example:
Allow dynamic-group DeployDG to use instance-agent-command-execution-family in compartment id
Allow dynamic-group DeployDG to read instances in compartment id
Allow dynamic-group DeployDG to read buckets in compartment id
Allow dynamic-group DeployDG to read objects in compartment id where target.bucket.name=''
Allow dynamic-group DeployDG to manage objects in compartment id where target.bucket.name=''
This allows the server to receive and execute commands.
Step 4: User IAM Policies
Example:
Allow group Admins to manage instance-agent-command-family in compartment id
Allow group Admins to read instance-agent-command-execution-family in compartment id
Allow group Admins to inspect instances in compartment id
What is ocarun in OCI Run Command?
ocarun is the local execution user/context used by OCI Run Command plugin on the compute instance.
When you send a command through Oracle Cloud Infrastructure Run Command, the instance agent receives it and executes it using the Run Command plugin. On many OCI images/platform setups, that execution is associated with ocarun.
-> If you run commands that required sudo privilages then you should provide ocarun user to the admin privilage.
Example Run Command (OCI CLI)
oci instance-agent command create \
--compartment-id \
--target '{"instanceId":""}' \
--content '{
"source":{
"sourceType":"TEXT",
"text":"hostname"
}
}' \
--timeout-in-seconds 600 \
--display-name test-hostname
Common Status Values Explained
lifecycle-state
Shows execution status.
ACCEPTED
Command created and queued.
IN_PROGRESS
Command is currently running.
SUCCEEDED
Command completed successfully.
FAILED
Command ran but failed.
CANCELED
Execution canceled.
To check the delivery status
oci instance-agent command-execution list --compartment-id ocid1.compartment.oc1..aaaaaaaagz4mern4sk46kbebwqzl6czdowlud7rop7ornezr7axx6ja5jfla --instance-id ocid1.instance.oc1.ap-mumbai-1.anrg6ljr7gqo7aacuco546smbzylzekybcfbvp2vz2ygvwgu52vf62zk7cma --all
delivery-state
Shows whether command reached the server.
ACKED
Server received the command.
EXPIRED
Command was never picked up before timeout window expired.
Usually caused by:
Wrong Dynamic Group
Agent issue
Network issue
Permissions issue
-> If you get delivery status ACKED and exit code =0 then your command / script successfully executed over the remote server.
How to Troubleshoot
Check Agent Status
Linux:
systemctl status oracle-cloud-agent
Restart Agent
systemctl restart oracle-cloud-agent
View Logs
tail -100 /var/log/oracle-cloud-agent/agent.log
Upload Detailed Logs to Object Storage
For long executions, store logs locally:
/tmp/deploy_httpd.log
Then upload logs back to bucket using automation.
This enables:
✔ Retention
✔ Audit trail
✔ Team review
✔ Full debugging
Security Best Practices
✔ Use least privilege IAM policies
✔ Restrict bucket access
✔ Sign scripts / validate source
✔ Avoid plaintext secrets in scripts
✔ Rotate credentials
Run Command vs SSH
| Feature | SSH | OCI Run Command |
|---|---|---|
| Needs inbound port | Yes | No |
| Manual session | Yes | No |
| API driven | Limited | Yes |
| Auditable | Moderate | Strong |
| Scalable fleet ops | Medium | Strong |
Final Thoughts
OCI Run Command is a powerful feature for remote server administration. Once properly configured, it becomes one of the easiest and safest ways to execute commands on OCI instances without direct login access.
If you manage OCI servers regularly, it is worth enabling and learning.
Top comments (0)